Annotated listings of files included in the 01-Sep-2001 TWiki distribution
Overview
This Appendix contains directory and file listings, and individual file descriptions, for the full 01-Sep-2001 TWiki distribution package.
Directory Structure
You can rename the root TWiki directory - twiki - to whatever you like by changing it in the twiki.cfg configuration file. However, to keep the current installation and future upgrades simple, you should leave the subdirectory structure intact:
Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Plugins/DefaultPlugin.pm
Handles some legacy rules
TWiki/Plugins/EmptyPlugin.pm
Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm
Use aliases as links for predefined URLs
Files under twiki/pub
The pub directory stores data-related files, including images used by TWiki and FileAttachments. Attachments are stored in sub-directories created with the related topic name. Partial file list:
TWiki page data stored as individual text files. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - Main, TWiki, Know, Test - with documentation and demo content, a Trash web, and a _default directory containing all topics required to start a new web. Partial file list:
Displays WebChanges list of recently changed topics
edit.iejs.tmpl
Edit window with IE specific JavaScript
edit.tmpl
Main edit window
mailnotify.tmpl
Email notification
moveattachment.tmpl
Control screen
oopsaccesschange.tmpl
Error message
oopsaccessgroup.tmpl
Error message
oopsaccessrename.tmpl
Error message
oopsaccessview.tmpl
Error message
oopsauth.tmpl
Error message
oopsbadpwformat.tmpl
Error message
oopschangepasswd.tmpl
Error message
oopsempty.tmpl
Error message
oopslocked.tmpl
Error message
oopslockedrename.tmpl
Error message
oopsmissing.tmpl
Error message
oopsmore.tmpl
More topic actions message
oopsmoveerr.tmpl
Error message
oopsnoformdef.tmpl
Error message
oopsnotwikiuser.tmpl
Error message
oopsnoweb.tmpl
Error message
oopspreview.tmpl
Error message
oopsregexist.tmpl
Error message
oopsregpasswd.tmpl
Error message
oopsregrequ.tmpl
Error message
oopsregthanks.tmpl
Error message
oopsregwiki.tmpl
Error message
oopsrenameerr.tmpl
Error message
oopsresetpasswd.tmpl
Error message
oopsrev.tmpl
Error message
oopssave.tmpl
Error message
oopssaveerr.tmpl
Error message
oopssendmailerr.tmpl
Error message
oopstopicexists.tmpl
Error message
oopsupload.tmpl
Error message
oopswrongpassword.tmpl
Error message
preview.tmpl
Preview Changes screen
rdiff.tmpl
Displays text changes before & after (Diffs)
register.tmpl
Registration page
registernotify.tmpl
Registration notification
rename.tmpl
Doing a new topic rename, user chooses web & topic
renamebase.tmpl
Used by other rename templates
renameconfirm.tmpl
Confirms a pre-specified rename, ex: undoing a rename
renamerefs.tmpl
Rename done, but some references not changed (topics were locked)
search.tmpl
Search screen
searchbookview.tmpl
Search results with full topic content
searchmeta.tmpl
Search screen
searchrenameview.tmpl
Used by rename to list references to topic being renamed
twiki.tmpl
Base template definitions used by other templates
view.plain.tmpl
Printable topic view with reduced header/footer
view.print.tmpl
Topic view without header/footer
view.tmpl
Main topic view
TWiki File System Snapshot
The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.
Directory twiki/bin:
BookView is part of search. It allows you to display the result in book view, e.g. the whole content of topcis is shown instead of a topic summary. This allows you to easily see a whole set of pages, which is useful for printing.
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
If you have questions please contact the Wiki webmaster webmaster@netfrag.org.
The default plugin is used for some deprecated rendering of older TWiki versions and of JosWiki. This plugin can also be used to specify some simple custom rendering rules. Note: Create a new TWikiPlugin based on EmptyPlugin if you plan to offer some complex rendering or other functionality.
Syntax Rules
Custom rendering rules of the default plugin:
Allow old include syntax ( %INCLUDE:"TopicName"% ) if Plugin Preferences variable OLDINCLUDE is set to 1
Render deprecated *_text_* as bold italic text. Test if installed: This is bold italic
Enable JosWiki rules if JosWiki specific code is uncommented
Modify file TWiki/Plugins/DefaultPlugin.pm to add your own rules or to enable JosWiki rules.
DefaultPlugin Settings
Plugin settings are stored as preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, i.e. %DEFAULTPLUGIN_SHORTDESCRIPTION%
New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously, these operations could only be done manually, by someone with file-level access to the Web server).
Moving lets you transfer a topic from one web to another. The soft delete moves a topic to the special Trash web, where it's hidden but can be "undeleted" with system administrator access.
Click [More] on the control bar at the bottom of the page you want to change, then choose [Rename/move], and make your changes that screen. There's a link that launches to the ManagingTopics reference page in a pop-up window.
NOTE: The configuration of your site and your own access permissions determine whether you can access these functions.
Back to:TWikiFAQ
-- MikeMannix - 14 Sep 2001
Use the "Minor changes, don't notify" checkbox in preview in case you only make a minor change to a topic and you do not want to inform everybody who is on the WebNotify list of the current web of this change.
Note: No new revision is created in case you save the same topic again within a certain time frame (default is one hour). You only need to checkmark the "Minor change, don't notify" checkbox once within this time frame, because subsequent save operations do not notify users.
Note: The initial state of the checkbox can be set to on with the DONTNOTIFYCHECKBOX preferences variable. See TWikiPreferences for more.
Why does the topic revision not increase when I edit a topic?
Answer:
The same topic revision will be used when you save a topic again within a certain time frame (one hour by default). This is to prevent unnecessary topic revisions when you do several edit cycles in a row. Note that a new revision is created if another person edits the same topic, regardless of the time.
Back to:TWikiFAQ
-- PeterThoeny? - 27 Nov 2000
This is an empty plugin you can use as a template to build your own TWikiPlugins. This plugin does nothing, but is ready to be used.
To create your own plugin:
Copy file TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm and customize the plugin.
Create a <name>Plugin topic in the TWiki web. Do so by visiting http://TWiki.org/cgi-bin/view/Plugins/ and starting a new topic to get the default plugin topic text (don't save the topic). Customize your plugin topic to your needs.
Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file.
Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.
What Are Attachments Good For?
File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.
Document Management System
You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis? using; create a central reference library that's easy to access and manage by an entire user group.
File Sharing
For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!
Web Authoring
Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.
Uploading Files
To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table?.
Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex: *.php files are renamed to *.php.txt.
Currently there is no file size limit besides the disk space on the server.
The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.
Downloading Files
To download: Click on the file in the File Attachment table?.
NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.
Moving Attachment Files
An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Deleting Attachments
It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.
Linking to Attached Files
Once a file is attached it can be referenced in the topic. Example:
GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
Attach file: Smile.gif
Edit topic and write text: %ATTACHURL%/Smile.gif
Preview - text appears as , an image.
File Attachment Contents Table
Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.
Clicking on an Action link takes you to a new page that looks like this:
The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.
The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.
Known Issues
Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute include h then the attachment is considered to be hidden. It is not listed for the topic, but is display when attach page is displayed.
-- JohnTalintyre - 30 Aug 2001
Inline search feature allows flexible formatting of search result
Overview
By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).
Syntax
Two paramters can be used to specify a customized search result:
1. header="..." parameter
Use the header paramter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. I.e. header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format paramter to specify the format of one search hit. I.e. format="| $topic | $summary |"
Variables that can be used in the format string:
Time stamp of last topic update, i.e. 27 Apr 2024 - 10:56
$isodate
Time stamp of last topic update, i.e. 2024-04-27T10:56Z
$rev
Number of last topic revision, i.e. 1.4
$wikiusername
Wiki user name of last topic update, i.e. Main.JohnSmith
$username
User name of last topic update, i.e. JohnSmith
$summary
Topic summary
$formfield(name)
The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$pattern(reg-exp)
A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
Examples
Bullet list showing topic name and summary
Write this:
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
Topic: Summary:
TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Table showing form field values of topics with a form
Write this in the Know web:
| *Topic:* | *OperatingSystem:* | *OsVersion:* | %SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
TWiki has a GPL (GNU General Public License). What is GPL?
Answer:
TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of the free software licenses that protects the copyright holder, and at the same time allows users to redistribute the software under the terms of the license. Extract:
This program is open source software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Please note that TWiki is not distributed under the LGPL (Lesser General Public Licence), which implies TWiki can only be used with software that is licensed under conditions compliant with the GPL. Embedding in proprietary software requires an alternative license. Contact the author for details.
Back to:TWikiFAQ
-- PeterThoeny? - 27 Nov 2000
OR, by all means, insert your comment where it seems to fit best:
you may want to inset it with a bullet and/or set it in italics so it's clear (always sign and date)
if a sub-topic develops, separate it with a horizontal rule at beginning and end
A good format for a new topic is "dissertation followed by discussion":
start with a brief, factual introduction, followed by double horizontal rules
let the discussion begin
When a discussion dies down and the page becomes static, if you're clear on your course, feel free to refactor mercilessly:
fearlessly edit down to capture the key points
reduce the noise without losing the facts or the flavor
if you merge or delete comments, group credit Contributors: at the end of the page
This is how Wiki content matures and grows in value over time.
For external site links, you can type URLs directly into the text - http://etcete.ra/... - it'll clear to anyone where they're headed on click.
TWiki is intended for world-wide use, and an international standard date format like 01 Sep 2001 is preferred. It's universally understood, and clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
TIP: Check the source when you want to find out how something is formatted: click Edit on the lower toolbar. To see earlier versions, click More, then check Raw text format and click View revision. A bit of HTML experience can't hurt, but you'll soon see with TWikiShorthand how far that is from necessary.
This plugin displays RSS feeds from news sites. Use it to build news portals that show headline news.
Note: Syndic8.com ( http://www.syndic8.com/ ) is a good site listing many RSS feeds.
HeadlinesPlugin Global Settings
Plugin settings are stored as preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, for example, %HEADLINES_SHORTDESCRIPTION%
Refresh rate in minutes for caching feed; "0" for no caching
Global REFRESH setting
limit
Maximum number of items shown
Global LIMIT setting
header
Header. Can include these variables: - $channeltitle: Title of channel - $channellink: Link of channel - $channeldescription: Description of channel - $imagetitle: Title text for site - $imagelink: Link for site - $imageurl: URL of image - $imagedescription: Description of image
Global HEADER setting
format
Format of one item. Can include these variables: - $title: News item title - $link: News item link - $description: News item description
Global FORMAT setting
Examples
Write %HEADLINES{ href="http://slashdot.org/slashdot.rdf" }% to get the latest Slashdot news in table format:
Write %HEADLINES{ href="http://www.moreover.com/cgi-local/page?o=rss&c=Aerospace%20and%20defense%20industry%20news" header=" * [[$channellink][$channeltitle]]:" format=" * [[$link][$title]] ($description)" }% to get Aerospace and defense industry news rendered as a bullet list:
Topic load time depends on timeit takes to load the RSS feed. A future version might include some caching to improve performance.
This plugin uses the undocumented TWiki::Net::getUrl() function. The plugin might break in a future TWiki release.
URLs on virtual hosts cannot be read, for example, TWiki:Codev/TWikiSyndication does not work. This is a limitation of TWiki::Net::getUrl()
Plugin Installation Instructions
Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
Download the ZIP file from the Plugin web (see below)
Unzip HeadlinesPlugin.zip in your twiki installation directory. Content:
We asked you to not click any question mark links!
Good thing we faked that one!
You can use your browser's back button or key to get back to the tutorial.
Include Topics and Web Pages Using %INCLUDE{...}% Variable
Use the %INCLUDE{...}% variable to embed the content of another topic or web page inside a netfrag.org topic. The whole content or only parts of a page can be included.
"page":
The nameless parameter specifies the page to include. It is
The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
A Web.Topic name specifying a topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
A full qualified URL with http protocol, domain name and optional port number, i.e. %INCLUDE{"http://twiki.org:80/index.html"}%. Supported content types are text/html and text/plain. The full page is included by default, but the HTML header and scripts are stripped in case it is a web page.
pattern="reg-exp":
The pattern parameter is optional and allows you to extract some parts of a web page. Specify a RegularExpression that scans from start ('^') to end and contains the text you want to keep in parenthesis, i.e. pattern="^.*?(from here.*?to here).*". You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
Note: All text of a topic is included unless you specify %STARTINCLUDE%, %STOPINCLUDE% and/or a pattern parameter.
Usage Examples
1. Display regression test results in a TWiki page
This topic lists all aliases needed to map Inter-Site links to external wikis/sites.
Whenever you write ExternalSite:Page it will be linked automatically to the page on the external site. The link points to the URL corresponding to the ExternalSite alias below, concatenated to the Page you choose. Example: Type Wiki:RecentChanges to get Wiki:RecentChanges, the RecentChanges page at the original Wiki site.
How to define Inter-Site links
Inter-Site links are defined in the tables below.
Each entry must be of format: | External site alias | URL | Tooltip help text |.
The URL and Tooltip Text may contain optional $page variables; the variable gets expanded to the page name.
Note: The Tooltip Text must not contain any HTML tags (including <nop> escape code), no internal WikiWord links, and no external links. Hint: Escape 'WikiWords' and '$page'.
27 Jul 2001 Allow numbers in site name 26 Jul 2001 Fixed alternating missed link bug due to greedy $postfixPattern (fix by Richard Donkin) 14 Jul 2001 Changed to plug & play 16 Jun 2001: Made tool tips optional; prevent Module::Sub type of link 12 Jun 2001: Added optional tool tips (IE only); added the link rules topic name variable; added flexible link patterns; optional $page in URL 10 Jun 2001: Changed rules topic to table based syntax 20 Feb 2001: Initial version
Browser-based rename, move, and delete for individual topics
Overview
Use browser controls while viewing a topic, to change its name, move it to another TWiki web, or delete it to a hidden Trash web.
How to Rename/Move/Delete a Topic
Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move].
Select target web if other than the current web - chose Trash to delete a topic?
Enter the new topic name - default is current name NOTE: You will be warned if there are locks or if there is a name conflict.
Select from the list of referring links any topics NOT to be updated with the new name (by default, all referring links will be updated).
Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
If any of the referring pages are locked then they will be listed.
You can correct these later by again pressing [Rename/Move].
Referring Topics
Referring topics are found using the the %SEARCH% variable, see the template searchrenameview.tmpl. First, matching topics in the current Web are listed - matches are to topic. Next, all Webs (including the current one) are listed that match web.topic. Because %SEARCH% is used, Webs marked in WebPreferences as NOSEARCHALL will not show up in the search for refernces to the topic being changed.
Changed references are kept are as short as possible, ex: topic is used in preference to web.topic.
About Deleting a Topic
Deleted topics are moved to the Trash web - NOT physically erased from the server. All webs share Trash - in case of a name conflict with a topic already Trash, the user is alerted and asked to choose a new name.
Clearing the Trash
The Trash web should be be cleared periodically, by archiving the contents if required (recommended), then deleting the files from the Trash directory.
%<nop>METASEARCH{type="topicmoved" web="TWiki" topic="ManagingTopics"
title="This topic used to exist and was moved to: "}%
Effect of Access Settings
Permissions affect the rename function in various ways. To rename a topic, you need both change and rename permissions. To alter refer4ing topics, you need change permission. See TWikiAccessControl for information on setting up access permissions.
How Rename/move Works
%SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
User can omit one or more topics from the update list.
<pre> and <verbatim> are honoured - no changes are made to text within these areas.
The topic is moved (if locks allow).
References are changed (locks and permissions permitting).
Any referring topics that can't be changed due to locks are listed - user can change them at another time.
Known Limitations
Rename/move in is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that search can show matches that will not be updated because of case differences. Other mismatches to actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]]
[[old topic]] => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]] => [[NewTopic]]
Adding, renaming and deleting webs are manual operations done directly on the server
Overview
Managing TWiki webs requires direct access to the installation files on the host server. There are currently no browser-based equivalents of the Rename/move/delete topic tools for working with webs.
Adding a New Web
Adding new webs is quick and easy - you can have a basic web up and running in a couple of minutes:
Create a new directory under twiki/data/, ex: twiki/data/Newweb
the name has to start with a capital and cannot be a WikiWord
NOTE: If you plan to rename the netfrag.org.Main web, remember that TWiki stores user and group topics in %MAINWEB%, default named Main. That means, every WikiName signature - Main.SomeUserName - points to it and would need updating (unless the variable, %MAINWEB%.SomeUserName, is used throughout).
Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic.
Make changes as required, to Newwebname.SomeTopic or better yet, to %MAINWEB%.SomeTopic.
Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable.
Edit the TWikiWebsTable topic: Rename or delete the web from the table.
Login to the netfrag.org server, via Telnet or FTP.
Go to twiki/data and rename or remove the web directory.
Go to twiki/templates and rename or remove the web directory if present.
Go to twiki/pub and rename or remove the web directory if present.
Various meta data can be stored in topics - MetaDataDefinition
This is rendered using the %META% variable. This is mostly used in the view, preview and edit scripts.
At present support is fairly basic:
Plugin settings are stored as preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, for example, %INTERWIKIPLUGIN_SHORTDESCRIPTION%
Background Image for Preview
Preview looks like the real page, but the links leed to an oops dialog warning users of not yet saved topics. In addition, a background with a "PREVIEW" watermark is shown to have visual clue that you are previewing a topic. You can change the background image by specifying the name of an attached background image file in the PREVIEWBGIMAGE variable in the TWikiPreferences.
Remarks:
You also could attach a new image file to this topic.
You can override the PREVIEWBGIMAGE preference variable in your personal home page.
Regular expressions (REs), unlike simple queries, allow you to search for text which matches a particular pattern.
REs are similar to (but more poweful than) the "wildcards" used in the command-line interfaces found in operating systems such as Unix and MS-DOS. REs are used by sophisticated search engines, as well as by many Unix-based languages and tools ( e.g., awk, grep, lex, perl, and sed ).
Examples
compan(y|ies)
Search for company , companies
(peter|paul)
Search for peter , paul
bug*
Search for bug , bugs , bugfix
[Bb]ag
Search for Bag , bag
b[aiueo]g
Second letter is a vowel. Matches bag , bug , big
b.g
Second letter is any letter. Matches also b&g
[a-zA-Z]
Matches any one letter (not a number and a symbol)
[^0-9a-zA-Z]
Matches any symbol (not a number or a letter)
[A-Z][A-Z]*
Matches one or more uppercase letters
[0-9][0-9][0-9]-[0-9][0-9]- [0-9][0-9][0-9][0-9]
US social security number, e.g. 123-45-6789
Here is stuff for our UNIX freaks:
(copied from 'man grep')
\c A backslash (\) followed by any special character is a
one-character regular expression that matches the spe-
cial character itself. The special characters are:
+ `.', `*', `[', and `\' (period, asterisk,
left square bracket, and backslash, respec-
tively), which are always special, except
when they appear within square brackets ([]).
+ `^' (caret or circumflex), which is special
at the beginning of an entire regular expres-
sion, or when it immediately follows the left
of a pair of square brackets ([]).
+ $ (currency symbol), which is special at the
end of an entire regular expression.
. A `.' (period) is a one-character regular expression
that matches any character except NEWLINE.
[string]
A non-empty string of characters enclosed in square
brackets is a one-character regular expression that
matches any one character in that string. If, however,
the first character of the string is a `^' (a circum-
flex or caret), the one-character regular expression
matches any character except NEWLINE and the remaining
characters in the string. The `^' has this special
meaning only if it occurs first in the string. The `-'
(minus) may be used to indicate a range of consecutive
ASCII characters; for example, [0-9] is equivalent to
[0123456789]. The `-' loses this special meaning if it
occurs first (after an initial `^', if any) or last in
the string. The `]' (right square bracket) does not
terminate such a string when it is the first character
within it (after an initial `^', if any); that is,
[]a-f] matches either `]' (a right square bracket ) or
one of the letters a through f inclusive. The four
characters `.', `*', `[', and `\' stand for themselves
within such a string of characters.
The following rules may be used to construct regular expres-
sions:
* A one-character regular expression followed by `*' (an
asterisk) is a regular expression that matches zero or
more occurrences of the one-character regular expres-
sion. If there is any choice, the longest leftmost
string that permits a match is chosen.
^ A circumflex or caret (^) at the beginning of an entire
regular expression constrains that regular expression
to match an initial segment of a line.
$ A currency symbol ($) at the end of an entire regular
expression constrains that regular expression to match
a final segment of a line.
* A regular expression (not just a one-
character regular expression) followed by `*'
(an asterisk) is a regular expression that
matches zero or more occurrences of the one-
character regular expression. If there is
any choice, the longest leftmost string that
permits a match is chosen.
+ A regular expression followed by `+' (a plus
sign) is a regular expression that matches
one or more occurrences of the one-character
regular expression. If there is any choice,
the longest leftmost string that permits a
match is chosen.
? A regular expression followed by `?' (a ques-
tion mark) is a regular expression that
matches zero or one occurrences of the one-
character regular expression. If there is
any choice, the longest leftmost string that
permits a match is chosen.
| Alternation: two regular expressions
separated by `|' or NEWLINE match either a
match for the first or a match for the
second.
() A regular expression enclosed in parentheses
matches a match for the regular expression.
The order of precedence of operators at the same parenthesis
level is `[ ]' (character classes), then `*' `+' `?'
(closures),then concatenation, then `|' (alternation)and
NEWLINE.
Request for reset of password
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will receive a page with yor new password appearing encrypted.
You will have to send this information to the Wiki webmaster webmaster@netfrag.org by email.
I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem.
Answer:
That is an indication that netfrag.org can't find the egrep and fgrep commands on your system. Check the $egrepCmd and $fgrepCmd variables in twiki/lib/TWiki.cfg.
Back to:TWikiFAQ
-- PeterThoeny? - 26 Jan 2001
What happens if two of us try to edit the same topic simultaneously?
Answer:
The second person gets a warning that the topic is currently being edited by another user. A topic gets locked automatically for some time (default is one hour) when you edit, preview or save the topic. If you get the lock warning you should wait until the lock is gone or contact the other person to ask if you can go ahead and break the lock. See also UnlockTopic.
Back to:TWikiFAQ
-- PeterThoeny? - 27 Nov 2000
This designates that a single word is a reference to a single word. To show TWiki that it should be linked to, write a dot before it.
Hence if you have the WikiWord Ontology you can link to it as .Ontology
In fact, you can already force a single word link to a WikiWord by enclosing it in double square brackets, like this: .Ontology?
This plugin allows you to write it without the square brackets.
The syntax was chosen to be an extension of the Web.Topic syntax
Test:
You can automatically generate usage statistics for all webs. To enable this:
Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in wikicfg.pm are set. This will generate log entries in file twiki/data/log<date>.txt .
Topic WebStatistics must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry: 0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example: 0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
Update current month for all webs: http://mydomain.com/twiki/bin/statistics
Update current month for Main web only: http://mydomain.com/twiki/bin/statistics/Main
Update January 2000 for Main web: http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
Restricting read and write access to topics and webs, by users and groups
Overview
TWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user groups, in three main areas: view; edit & attach; and rename/move/delete. These controls, combined with TWikiUserAuthentication, let you easily create and manage an extremely flexible, fine-grained privilege system.
An Important Control Consideration
Open, freeform editing is the essence of the WikiCulture - it's what makes TWiki different and often more effective than other collaboration tools. So, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care. Experience shows that unrestricted write access works very well because:
Peer influence is enough to ensure that only relevant content is posted.
Peer editing - the ability to rearrange anything on a page - keeps topics focussed.
All content is preserved under revision control.
Edits can be undone by the TWikiAdminGroup (the default administrators group; see #ManagingGroups).
Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a collaboration guideline:
Create broad groups (more and varied input), and...
Avoid creating view-only users (if you can read it, you can contribute to it).
Users and Groups
Access control is based on users and groups. Users are defined by their WikiNames, an then organized into unlimited combinations under different user groups.
Managing Users
A user is created by with the TWikiRegistration form. The process generates a topic in the Main web in the new user's WikiName. The default visitor name is TWikiGuest?.
Users can be authenticated using Basic Authentication or SSL. TWikiUserAuthentication is required in order to track user identities.
Managing Groups
Groups are defined by group topics in the Main web, like the TWikiAdminGroup. To start a new group:
Create a new topic with A name that ends in Group, SomeGroup
Define two variables:
Set GROUP = < list of users and groups >
Set ALLOWTOPICCHANGE = < list of users and groups >
GROUP is a comma-separated list of users and of other groups: Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeOtherGroup
ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic, Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
for the TWikiAdminGroup topic. (This prevents users not in the group from editing the topic and from gaining unauthorized membership to the group.)
Restricting Write Access
You can define who is allowed to make changes to a web or a topic.
Deny Editing by Topic
Denying editing of a topic also restricts attaching files to it; both privileges are assigned together.
Define one or both of these variables in a topic, preferably at the end of the page:
Set DENYTOPICCHANGE = < list of users and groups >
Set ALLOWTOPICCHANGE = < list of users and groups >
DENYTOPICCHANGE defines users or groups that are not allowed to make changes to the topic. It is a comma delimited list of users and groups. Example: * Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICCHANGE defines users or groups that are allowed to make changes to the topic. It is a comma delimited list of users and groups. Example: * Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.
Deny Editing by Web
Restricting web-level editing blocks creating new topics, changing topics or attaching files.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBCHANGE = < list of users and groups >
Set ALLOWWEBCHANGE = < list of users and groups >
The same rules apply as for restricting topics, with these additions:
DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)
Restricting Rename Access
You can define who is allowed to rename, move or delete a topic, or rename a web.
Deny Renaming by Topic
To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.
Define one or both of these variables in a topic, preferably at the end of the topic:
Set DENYTOPICRENAME = < list of users and groups >
Set ALLOWTOPICRENAME = < list of users and groups >
DENYTOPICCRENAME defines users or groups that are not allowed to rename the topic. It is a comma delimited list of users and groups. Example: * Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICRENAME defines users or groups that are allowed to rename the topic. It is a comma delimited list of users and groups. Example: * Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICRENAME is evaluated before ALLOWTOPICRENAME. Access is denied if the authenticated person is in the DENYTOPICRENAME list, or not in the ALLOWTOPICRENAME list. Access is granted in case DENYTOPICRENAME and ALLOWTOPICRENAME is not defined.
Deny Renaming by Web
You can define restrictions of who is allowed to rename a netfrag.org web.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBRENAME = < list of users and groups >
Set ALLOWWEBRENAME = < list of users and groups >
The same rules apply as for topics, with these additions:
DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)
Restricting Read Access
You can define restrictions of who is allowed to view a netfrag.org web.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBVIEW = < list of users and groups >
Set ALLOWWEBVIEW = < list of users and groups >
Known Issues
The view restriction is not suitable for very sensitive content since there is a way to circumvent the read access restriction.
Read access restriction only works if the view script is authenticated, that means that users need to log on also just to read topics. TWikiInstallationGuide has more on Basic Authentication based on the .htaccess file.
Selective Unrestricted Web Access
There is a workaround if you prefer to have unrestricted access to view topics located in normal webs, and to authenticate users only for webs where view restriction is enabled:
Omit the view script from the .htaccess file.
Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. netfrag.org will now remember the IP address of an authenticated user.
Copy the view script to viewauth (or better, create a symbolic link)
Addviewauth to the list of authenticated scripts in the .htaccess file.
When a user accesses a web where you enabled view restriction, netfrag.org will redirect from the view script to the viewauth script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth script shows the requested topic if the user could log on and if the user is authorized to see that web.
If you enable view restriction for a web, it is recommended to restrict search "all webs" from searching this web. Enable this restriction with the NOSEARCHALL variable in its WebPreferences, like:
Set NOSEARCHALL = on
It is not recommended to restrict view access to individual topics since all content is searchable within a web.
Hiding Control Settings
To hide access control settings from normal browser viewing, place them in comment markers.
<!--
Set DENYTOPICCHANGE = Main.SomeGroup
-->
The SuperAdminGroup
By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that it no-one can edit it from a browser. To avoid this:
Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of users that are always allowed to edit/view topics.
A TWiki contributor is a person devoting his/her time to contribute on the development of the Open Source project TWiki, hosted at http://TWiki.org/ . It is defined as a person who:
has contributed code that was accepted into the TWiki distribution, or
has considerably contributed to the TWiki documentation.
I would like to take this opportunity to express my appreciation to all who contributed ideas, code, fixes and documentation.
TWiki Reference Manual (01-Dec-2001)
This page contains all documentation topics as one long, complete reference sheet. Doubleclick anywhere to return to the top of the page.
Server and client system requirements for TWiki 01-Sep-2001
Overview
Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.
Server Requirements
TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements:
Required Server Environment
Resource
Unix
Windows
Perl
5.005_03 or higher
Non standard Perl modules
Net::SMTP (or sendmail)
Net::SMTP, MIME::Base64, Digest::SHA1
RCS
5.7 or higher
Other external programs
ls, fgrep, egrep
Web server
Apache; others (with support for CGI, authentication, extended path) *
Current documentation covers Linux only. A TWikiOnWindows installation guide is next.
generates XHTML 1.0 pages that are compatible with HTML 3.2
minimal use of JavaScript in the user interface (degrades gracefully)
no cookies
no CSS
You can easily add capabilities, through customizing the templates, for one, while tailoring the browser requirements to your situation.
Known Issues
The new TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything: browser-specific functions, stylesheets (CSS), DHTML, Java applets, cookies.
Installation instructions for the TWiki 01-Sep-2001 production release
Overview
These installation steps are based on the Apache Web server on Linux. TWiki runs on other Web servers and Unix systems, and should be fine with any OS and server that meet the system requirements. Documentation for other platforms is currently limited. For Windows, check TWiki:Codev/TWikiOnWindows. Search the TWiki:Codev web for other intallation notes.
Standard Installation
Request and download the TWiki 01-Sep-2001 distribution in Unix ZIP format from http://TWiki.org/download.html. (To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/SourceForgeHowTo.)
Step 1: Create & Configure the Directories
NOTE:If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account - use the alternative Step 1? instead.
Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file /etc/httpd/httpd.conf with only ExecCGI option.
The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
NOTE: The ScriptAliasmust come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
Example httpd.conf entries:
ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
Alias /twiki/ "/home/httpd/twiki/"
<Directory "/home/httpd/twiki/bin">
Options +ExecCGI
SetHandler cgi-script
AllowOverride all
Allow from all
</Directory>
<Directory "/home/httpd/twiki/pub">
Options FollowSymLinks +Includes
AllowOverride None
Allow from all
</Directory>
Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.
Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
IMPORTANT: On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary.
Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
NOTE: This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
replace user twiki with your own username
Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
NOTE: The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using sed: for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Step 3: Set the Main Configuration File
Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
Set the file extension in the $scriptSuffix variable to cgi or pl if required.
Make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to mach the location of your RCS binaries.
Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.
Step 4: Finish Up from Your Browser
Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
Edit the TWikiPreferences topic in the TWiki:TWiki web to set the WIKIWEBMASTER email address, and other preferences.
Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
Enable email notification of topic changes, TWikiSiteTools has more.
Edit the WebNotify topic in all webs and add the users you want to notify.
That's it for the standard virgin installation of TWiki. Read on for server-level customization options.
Additional Server-Level Options
With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.
Enabling Authentication of Users
If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly: Redirect /urlpath/to/TWiki/index.html http://your.domain.com/urlpath/to/TWiki/bin/view AuthUserFile /filepath/to/TWiki/data/.htpasswd ErrorDocument 401 /urlpath/to/TWiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
NOTE: In case you renamed the CGI script files to have a file extension you need to reflect that in the edit, view, preview, etc entries in .htaccess.
NOTE: The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.
Copy the TWikiRegistrationPub topic to TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
HINT: You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are processed correctly.
NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
Create a new topic to check if authentication works.
Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
Edit the WebPreferences topic in each web, if necessary: set access priviliges.
Adding a New Web
To create a new web:
Create a new web data directory under twiki/data and check the file permission of the directory.
Use a name starting with characters A..Z, followed by a..z and/or 0..9 characters, but not a WikiWord.
Copy all files from the twiki/data/_default directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use cp -p). The data files must be writable by the owner the CGI scripts are running on (usually, nobody).
HINT: You can set permissions of .txt and .txt,v files to -rw-rw-rw- (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
Add the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, TWikiPreferences:
Add the new web to the %WIKIWEBLIST% variable.
Update the web settings by editing the WebPreferences topic of the new web:
Customize the %WEBTOPICLIST% variable to contain the web-specific links you prefer.
Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
Set Plugins, access privileges, custom variables, other web-level options (ex: %WEBCOPYRIGHT% can be set for an individual web).
Add the new web to the color-coded web directory table by editing the TWikiWebsTable topic.
Test the new web: view pages, create a new page.
That's it for a basic new web set-up!
Optionally, you can also:
Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.
NOTE: User home topics are located in the netfrag.org.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to netfrag.org.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!
Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release)
Overview
This guide describes how to upgrade either from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001.
The latest version of TWiki (01-Dec-2001) is a small incremental release over the 01-Sep-2001 version.
The 01-Sep-2001 version involves several major new features and numerous enhancements to the last full version (01-Dec-2000). The file system set-up is almost identical, but much of the underlying data structure and processes is new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.
Upgrade Requirements
To upgrade from a 01-Dec-2000 or 01-Sep-2001 standard installation to the latest 01-Dec-2001 TWiki Production Release, follow the instructions below.
To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.
Major Changes from TWiki 01-Sep-2001
The latest 01-Dec-2001 release includes the following new features and enhancements compared to the 01-Sep-2001 release:
FormattedSearch - New format="" parameter in %SEARCH{}% variable for database like reporting.
Various bug fixes
Major Changes from TWiki 01-Dec-2000
The 01-Sep-2001 release includes the following new features and enhancements compared to the 01-Dec-2000 release:
TWikiPlugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
InterwikiPlugin (preinstalled) - Link to external sites with text aliases, SiteAlias:Page; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.)
SuperAdministrator Group - Lets you to make the members of one user group - by default, TWikiAdminGroup - into TWiki superusers, with the ability to overwrite locked topics from the browser interface. (This gets around the problem of topic lockouts, caused by typos in access privilege definitions.)
HierarchicalNavigation uses new Meta Data variables to link hierarchically.
Convert to XHTML - Pages are rendered for display in XHTML 1.0, as far as possible without breaking HTML 3.2 compliance.
TWiki Directory Structure and File Names
The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:
A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.
Standard Upgrade Procedure from 01-Sep-2001 to 01-Dec-2001 Release
This incremental update can be performed easily.
The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Sep-2001 release.
Back up and prepare:
Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.
Create a temporary directory and unpack the ZIP file there.
Update files in TWiki root:
Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
Update template files:
Overwrite all template files in $TWIKIROOT/templates with the new ones.
Update script files:
Overwrite all script files in $TWIKIROOT/bin with the new ones.
Update library files:
Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
Overwrite all *.pm library files in $TWIKIROOT/lib/TWiki and $TWIKIROOT/lib/TWiki/Plugins with the new ones.
Update data/TWiki files: (in case you want the updated docs)
Using your browser, merge the new TWiki.TWikiRegistration topic (or TWiki.TWikiRegistrationPub in case you used that one) into your existing TWiki.TWikiRegistration topic.
In the temporary twiki/data/TWiki directory where you unzipped the installation package:
Remove the files you do not want to upgrade: TWikiPreferences.*, TWikiWebsTable.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory.
Update pub/TWiki files:
Move the new pub/TWiki/TWikiDocGraphics directory into your $TWIKIROOT/pub/TWiki directory.
Standard Upgrade Procedure from 01-Dec-2000 to 01-Dec-2001 Release
The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.
Before Switch:
After Switch:
Current 01-Dec-2000:
New 01-Dec-2001:
Obsolete 01-Dec-2000:
New 01-Dec-2001:
twiki/templates/
twiki/templates2/
twiki/templates1/
twiki/templates/
twiki/bin/
twiki/bin/2/
(overwritten)
twiki/bin/
(N/A)
twiki/bin/lib/
(N/A)
twiki/lib/
twiki/data/TWiki
twiki/data/TWiki2
twiki/data/TWiki1
twiki/data/TWiki
(other directories do not change)
Alternatively you could move the existing installation away, install the 01-Dec-2001 release into it's place and move your webs and pub files back.
Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Dec-2001 release, importing your original page data and related files:
Pre-Upgrade Preparation
Two major areas of TWiki functionality - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.
The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/
Step 1: Backup & Unpack
Back up all existing TWiki directories twiki/bin, twiki/pub, twiki/data, twiki/templates.
Create a temporary directory and unpack the ZIP file there:
mkdir -p ~/tmp/ cp -p ~/downloads/TWiki20011201.zip ~/tmp/ cd ~/tmp/ unzip ~/tmp/TWiki20011201.zip
Step 2: Upgrade TWiki document files
Move the document files to your TWiki root ( twiki ):
mv ~/tmp/TWiki*.html $TWIKIROOT mv ~/tmp/index.html $TWIKIROOT mv ~/tmp/readme.txt $TWIKIROOT mv ~/tmp/license.txt $TWIKIROOT
Step 3: Install new template files
Move & rename the template directory to a temporary twiki/templates2 directory, ex:
mv ~/tmp/templates $TWIKIROOT/templates2
Pay attention to the file and directory permissions (security issue). Set file permissions, ex:
chmod 644 *.cgi
Step 4: Install new data and pub files
Move the TWiki web to a temporary TWiki2 twiki/data/TWiki2 directory. Do the same to files attached to this web, ex:
mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2 mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2
Move & rename the Know web to a temporary twiki/data/Know2 directory, ex:
mv ~/tmp/data/Know $TWIKIROOT/data/Know2 mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2
Move the _default and Trash web, ex:
mv ~/tmp/data/_default $TWIKIROOT/data mv ~/tmp/data/Trash $TWIKIROOT/data
Move the MIME types file, ex:
mv ~/tmp/data/mime.types $TWIKIROOT/data
Move the TWiki logo files, ex:
mv ~/tmp/pub/*.gif $TWIKIROOT/pub
Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).
In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Step 5: Install new CGI scripts
Move & rename the CGI script directory to a temporary twiki/bin/2 directory, ex:
mv ~/tmp/bin $TWIKIROOT/bin/2
If necessary, change the script names to include the required extension, ex: .cgi
Copy any additional scripts you might have from the 01-Dec-2000 release, ex:
cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2
In case you use basic authentication, rename .htaccess.txt to .htaccess and customize it, ex:
cd $TWIKIROOT/bin/2 mv .htaccess.txt .htaccess diff ../.htaccess . and merge the content
Pay attention to the file and directory permissions (security issue). Set permissions, ex:
chmod 755 *.cgi
Step 6: Install new Perl library files
Move the lib directory to a temporary twiki/bin/lib directory, ex:
mv ~/tmp/lib $TWIKIROOT/bin
Pay attention to the file and directory permissions (security issue). Set permissions, ex:
chmod 644 *.pm
Step 7: Set configurations and test installation
Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
cd $TWIKIROOT/bin/lib diff ../wikicfg.pm TWiki.cfg
Make sure to set the correct temporary location of templates and scripts, ex:
$scriptUrlPath = "/twiki/bin/2"; $templateDir = "/home/httpd/twiki/templates2";
Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm
Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:
Old URL: http://localhost/cgi-bin/view
New URL: http://localhost/cgi-bin/2/view
Step 8: Update topics
You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Dec-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.
Remember that you now have two TWiki webs:
The original TWiki web.
The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.
In case you customized TWiki.TWikiRegistration, merge your changes back into TWiki2.TWikiRegistration.
Copy TWiki.TWikiWebsTable to TWiki2.TWikiWebsTable.
Do the same for any other topics you might have created in the TWiki web.
In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.
Add your webs to WIKIWEBLIST
Set the WIKIWEBMASTER
Set the SMTPMAILHOST
In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)
Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
* Set NOSEARCHALL = on
In WEBTOPICLIST, remove the %WEB% . {} decoration from the list (it is now in the templates), ex:
* Set WEBTOPICLIST = <a href="Home">Home</a> | <a href="WebChanges">Changes</a> | <a href="WebIndex">Index</a> | <a href="WebSearch">Search</a> | Go <input type="text" name="topic" size="16" />
Add a these new preferences:
* Set DENYWEBVIEW = * Set ALLOWWEBVIEW = * Set DENYWEBRENAME = * Set ALLOWWEBRENAME =
Set the FINALPREFERENCES:
* Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
Optional: In WebSearch of all webs, replace content with this one line:
%INCLUDE{"%TWIKIWEB%.WebSearch"}%
Optional: In WebChanges of all webs, replace content with this one line:
%INCLUDE{"%TWIKIWEB%.WebChanges"}%
Step 9: Customize template files
NOTE: Skip this step if you did not customize your template files.
Remember that you have now two template directories:
The original twiki/templates.
The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.
Customized templates and skins need to be upgraded to the new TWikiTemplates. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.
Create a replacement WebForm topic based on twikicatitems.tmpl in each web that uses a Category Table. See details in TWikiForms and compare with the settings in the Know2.WebPreferences topic.
NOTE: Do not remove the twikicatitems.tmpl file, it is still used for topics that are of the old format.
Searches need to be adjusted to deal with format change. It is possible to define a regular expression search that can deal at the same time with topics in the old format and new format.
Example: List all topics in the Know web that have a TopicClassification? of PublicFAQ?: %SEARCH{ "[T]opicClassification.*?(td..td|value\=).*?[P]ublicFAQ" casesensitive="on" regex="on" nosearch="on" web="Know"}% (The [T] and [P] is done so that search does not find the topic where this search string is located in!)
Example: Create a link that lists all topics in the Know web with a TopicClassification? of PublicFAQ?: [[%SCRIPTURL%/search%SCRIPTSUFFIX%/Know/?scope=text &search=%5BT%5DopicClassification.*%3F%28td..td%7C value%5C%3D%29.*%3F%5BP%5DublicFAQ®ex=on][All Public FAQ]] All Public FAQ
For each web that has a custom notedited.tmpl template, create an equivalent WebTopicEditTemplate to conform with the new TemplateTopics. The new format replaces the notedited.tmpl, notext.tmpl and notwiki.tmpl templates.
Step 10: Switch over to new installation
In this step, you move the working 01-Dec-2001 installation to the old 01-Dec-2000 installation, so that users don't have to change the URL.
Test your new 01-Dec-2001 installation under twiki/bin/2/view to make sure everything works as expected.
NOTE: Don't worry about the Plugins, they'll work after the switch.
Edit $TWIKIROOT/bin/2/TWiki.cfg and remove the /2 from $scriptUrlPath and $templateDir, ex:
$scriptUrlPath = "/twiki/bin"; $templateDir = "/home/httpd/twiki/templates";
Rename the TWiki2 web to TWiki, including attachments, ex:
cd $TWIKIROOT/data mv TWiki TWiki1 mv TWiki2 TWiki cd $TWIKIROOT/pub mv TWiki TWiki1 mv TWiki2 TWiki
Rename the templates2 directory to templates, ex:
cd $TWIKIROOT mv templates templates1 mv templates2 templates
Move the lib directory one level up from $TWIKIROOT/bin/lib to $TWIKIROOT/lib, ex:
cd $TWIKIROOT mv bin/lib .
Copy content of bin/2 to bin, ex:
cd $TWIKIROOT/bin cp -p bin/2/* . cp -p bin/2/.htaccess .
Point your browser to the original URL and make sure the relocated 01-Dec-2001 installation works as expected: check browsing, searching and user registration.
The EmptyPlugin, DefaultPlugin, and InterwikiPlugin should be preinstalled. To check the InterwikiPlugin, go to its page.
If you have customized the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE and extendGetRenderedVersionInsidePRE in twiki/bin/wikicfg.pm:
Merge those changes back into twiki/lib/TWiki/Plugins/Default.pm
General Format Changes
The format of the %GMTIME{"..."}% and %SERVERTIME{"..."}% variables is now "$hour:$min" instead of "hour:min". More in TWikiVariables.
ExtendingTableSyntax: Enhanced table syntax might have unwanted side effect: | *bold* | cells, | center aligned | and | right aligned | cells, span multiple columns using | empty cells |||. More in TextFormattingRules.
Use Net::SMTP module instead of sendmail if installed.
Use <verbatim> ... </verbatim> tags instead of <pre> ... </pre> tags where appropriate. More in TextFormattingRules.
New variable %STARTINCLUDE% and %STOPINCLUDE% variables to control what gets included of a topic. More in TWikiVariables.
Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.
Attachments are now under revision control: $attachAsciiPath in TWiki.cfg defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.
Handling for topic-specific templates like edit.new.tmpl has been removed and replaced by template topics in the new TWikiTemplates.
A new file warning.txt file can appear in the data directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.
TWiki site access control and user activity tracking
Overview
TWiki does not authenticate users internally, it depends on the REMOTE_USER environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).
TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.
Authentication Options
No special installation steps are required if the server is already authenticated. If it isn't, you have three standard options for controlling user access:
Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest? default identity, so you can't track individual user activity.
Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server.
Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit=, installpasswd, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.
Partial Authentication
Tracking by IP address is an experimental feature, enabled in lib/TWiki.cfg. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:
Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.
TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest?.
Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.
NOTE: This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.
Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:
This section applies only if your netfrag.org is installed on a server that is both authenticated and on an intranet.
netfrag.org internally manages two usernames: Login username and TWiki username.
Login username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to netfrag.org by the REMOTE_USER environment variable, and used by internally by netfrag.org. Login usernames are maintained by your system administrator.
TWiki username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the Main web.
netfrag.org can automatically map an intranet username to a TWiki username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.
NOTE:To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Main.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the netfrag.org.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.
Changing Passwords
Change and reset passwords using forms on regular pages. Use TWikiAccessControl to restrict use as required.
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
Request for reset of password
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will receive a page with yor new password appearing encrypted.
Restricting read and write access to topics and webs, by users and groups
Overview
TWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user groups, in three main areas: view; edit & attach; and rename/move/delete. These controls, combined with TWikiUserAuthentication, let you easily create and manage an extremely flexible, fine-grained privilege system.
An Important Control Consideration
Open, freeform editing is the essence of the WikiCulture - it's what makes TWiki different and often more effective than other collaboration tools. So, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care. Experience shows that unrestricted write access works very well because:
Peer influence is enough to ensure that only relevant content is posted.
Peer editing - the ability to rearrange anything on a page - keeps topics focussed.
All content is preserved under revision control.
Edits can be undone by the TWikiAdminGroup (the default administrators group; see #ManagingGroups).
Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a collaboration guideline:
Create broad groups (more and varied input), and...
Avoid creating view-only users (if you can read it, you can contribute to it).
Users and Groups
Access control is based on users and groups. Users are defined by their WikiNames, an then organized into unlimited combinations under different user groups.
Managing Users
A user is created by with the TWikiRegistration form. The process generates a topic in the Main web in the new user's WikiName. The default visitor name is TWikiGuest?.
Users can be authenticated using Basic Authentication or SSL. TWikiUserAuthentication is required in order to track user identities.
Managing Groups
Groups are defined by group topics in the Main web, like the TWikiAdminGroup. To start a new group:
Create a new topic with A name that ends in Group, SomeGroup
Define two variables:
Set GROUP = < list of users and groups >
Set ALLOWTOPICCHANGE = < list of users and groups >
GROUP is a comma-separated list of users and of other groups: Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeOtherGroup
ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic, Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
for the TWikiAdminGroup topic. (This prevents users not in the group from editing the topic and from gaining unauthorized membership to the group.)
Restricting Write Access
You can define who is allowed to make changes to a web or a topic.
Deny Editing by Topic
Denying editing of a topic also restricts attaching files to it; both privileges are assigned together.
Define one or both of these variables in a topic, preferably at the end of the page:
Set DENYTOPICCHANGE = < list of users and groups >
Set ALLOWTOPICCHANGE = < list of users and groups >
DENYTOPICCHANGE defines users or groups that are not allowed to make changes to the topic. It is a comma delimited list of users and groups. Example: * Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICCHANGE defines users or groups that are allowed to make changes to the topic. It is a comma delimited list of users and groups. Example: * Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.
Deny Editing by Web
Restricting web-level editing blocks creating new topics, changing topics or attaching files.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBCHANGE = < list of users and groups >
Set ALLOWWEBCHANGE = < list of users and groups >
The same rules apply as for restricting topics, with these additions:
DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)
Restricting Rename Access
You can define who is allowed to rename, move or delete a topic, or rename a web.
Deny Renaming by Topic
To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.
Define one or both of these variables in a topic, preferably at the end of the topic:
Set DENYTOPICRENAME = < list of users and groups >
Set ALLOWTOPICRENAME = < list of users and groups >
DENYTOPICCRENAME defines users or groups that are not allowed to rename the topic. It is a comma delimited list of users and groups. Example: * Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICRENAME defines users or groups that are allowed to rename the topic. It is a comma delimited list of users and groups. Example: * Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICRENAME is evaluated before ALLOWTOPICRENAME. Access is denied if the authenticated person is in the DENYTOPICRENAME list, or not in the ALLOWTOPICRENAME list. Access is granted in case DENYTOPICRENAME and ALLOWTOPICRENAME is not defined.
Deny Renaming by Web
You can define restrictions of who is allowed to rename a netfrag.org web.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBRENAME = < list of users and groups >
Set ALLOWWEBRENAME = < list of users and groups >
The same rules apply as for topics, with these additions:
DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)
Restricting Read Access
You can define restrictions of who is allowed to view a netfrag.org web.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBVIEW = < list of users and groups >
Set ALLOWWEBVIEW = < list of users and groups >
Known Issues
The view restriction is not suitable for very sensitive content since there is a way to circumvent the read access restriction.
Read access restriction only works if the view script is authenticated, that means that users need to log on also just to read topics. TWikiInstallationGuide has more on Basic Authentication based on the .htaccess file.
Selective Unrestricted Web Access
There is a workaround if you prefer to have unrestricted access to view topics located in normal webs, and to authenticate users only for webs where view restriction is enabled:
Omit the view script from the .htaccess file.
Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. netfrag.org will now remember the IP address of an authenticated user.
Copy the view script to viewauth (or better, create a symbolic link)
Addviewauth to the list of authenticated scripts in the .htaccess file.
When a user accesses a web where you enabled view restriction, netfrag.org will redirect from the view script to the viewauth script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth script shows the requested topic if the user could log on and if the user is authorized to see that web.
If you enable view restriction for a web, it is recommended to restrict search "all webs" from searching this web. Enable this restriction with the NOSEARCHALL variable in its WebPreferences, like:
Set NOSEARCHALL = on
It is not recommended to restrict view access to individual topics since all content is searchable within a web.
Hiding Control Settings
To hide access control settings from normal browser viewing, place them in comment markers.
<!--
Set DENYTOPICCHANGE = Main.SomeGroup
-->
The SuperAdminGroup
By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that it no-one can edit it from a browser. To avoid this:
Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of users that are always allowed to edit/view topics.
Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all layed out below - refer back to this page in a pop-up window from the Edit screen.
TWiki Editing Shorthand
Formatting Command:
Example: You write:
You get:
Paragraphs:
Blank lines will create new paragraphs.
1st paragraph
2nd paragraph
1st paragraph
2nd paragraph
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables.
---++ Sushi
---+++ Maguro
Sushi
Maguro
Bold Text:
Words get bold by enclosing them in * asterisks.
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores.
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
=Fixed font=
Fixed font
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
==Bold fixed==
Bold fixed
Note: Make sure to "stick" the * _ = == signs to the words, e.g. take away spaces.
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted. Note: Each tag must be on a line by itself.
Separator:
At least three dashes at the beginning of a line.
-------
List Item:
Three spaces and an asterisk.
* bullet item
bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
* nested stuff
nested stuff
Ordered List:
Three spaces and a number.
1 Sushi
1 Dim Sum
Sushi
Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition. Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the non-breaking-space entity.
Sushi: Japan
Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars. Note:| *bold* | cells are rendered as table headers. Note:| spaced | cells are rendered center aligned. Note:| spaced | cells are rendered right aligned. Note:| 2 colspan || cells are rendered as multi-span columns. Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different netfrag.org web write Webname.TopicName.
#SquareBrackets
Forced Links:
You can create a forced internal link by enclosing words in double square brackets. Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
Anchors:
You can define a link reference inside a netfrag.org topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
[[WebHome#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS
Using HTML
You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
HTML and TWiki Usability
On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand? instead - this keeps the text uncluttered and easy to edit.
NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
TWiki HTML Rendering
TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
NOTE: The opening and closing angle brackets - <...> - of an HTML tag must be on the same line, or the tag will be broken.
This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, <, ex: a > b
If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
Hyperlinks
Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
Internal Links
GoodStyle is a WikiWord that links to the GoodStyle topic located in the current netfrag.org web.
NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
External Links
http://..., https://..., ftp://... and mailto:...@... are linked automatically.
Email addresses like name@domain.com are linked automatically.
[[Square bracket rules]] let you easily create non-WikiWord links?.
TWikiPlugin Formatting Extensions
Plugins provide additional text formatting capabilities and can extend the functionality of netfrag.org into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.
Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
HeadlinesPlugin: Build news portals that show headline news based on RSS news feeds from news sites.
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
TablePlugin: Control attributes of tables and sorting of table columns
VisualConfirmPlugin: Plugin for visual confirmation of new user registration.
Check on current Plugin status and settings for this site in TWikiPreferences.
-- MikeMannix? - 02 Dec 2001
TWiki Variables
Text strings expanded on the fly to display data or system info
Overview
TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.
Predefined Variables
Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.
netfrag.org expands the following variables (enclosed in % percent signs):
Variable:
Expanded to:
%WIKIHOMEURL%
The base script URL of netfrag.org, is the link of the Home icon in the upper left corner, is http://TWiki.org/
%SCRIPTURL%
The script URL of netfrag.org, is http://netfrag.org/twiki/bin
%SCRIPTURLPATH%
The path of the script URL of netfrag.org, is /twiki/bin
%SCRIPTSUFFIX%
The script suffix, ex: .pl, .cgi is
%PUBURL%
The public URL of TWiki, is http://netfrag.org/twiki/pub
%PUBURLPATH%
The path of the public URL of netfrag.org, is /twiki/pub
%ATTACHURL%
The attachment URL of the current topic, is http://netfrag.org/twiki/pub/TWiki/TWikiVariables Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH%
The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}%
Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME%
Name of wiki tool, is netfrag.org
%WIKIVERSION%
Wiki tool version is 04 Sep 2004 $Rev: 1742 $
%USERNAME%
Your login username is guest
%WIKINAME%
Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is TWikiGuest
%WIKIUSERNAME%
Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.TWikiGuest
%MAINWEB%
The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups?. Is Main
%TWIKIWEB%
The web containing all documentation and configuration of netfrag.org is TWiki
%WEB%
The current web is TWiki
%BASEWEB%
The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB%
The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC%
The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC%
The web preferences topic. Is WebPreferences
%STATISTICSTOPIC%
The web statistics topic. Is WebStatistics
%TOPIC%
The current topic name, is TWikiVariables
%BASETOPIC%
The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC%
The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC%
The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}%
Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
Parameters are format, separator and web:
Format of one line, may include $name and $web variables
"$name"
format="format"
(Alternative to above)
"$name"
separator=", "
line separator
"\n" (new line)
web="Name"
Name of web
Current web
Examples:
%TOPICLIST{" * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}%
Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
Parameters are format, separator and web:
comma sep list of Web, public expands to all non-hidden
"public"
marker="selected"
Text for $marker where item matches selection, otherwise equals ""
"selected"
selection="%WEB%"
Current value to be selected in list
section="%WEB%"
Examples: %WEBLIST{" * [[$name.Home]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
Variables can be shortened to 3 characters. Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% is 27 Apr, 2024 - 10:56:15
%SERVERTIME%
Server time, is 27 Apr 2024 - 12:56
%SERVERTIME{"format"}%
Formatted server time. Example: %SERVERTIME{"$hou:$min"}% is 12:56
%HTTP_HOST%
HTTP_HOST environment variable, is netfrag.org
%REMOTE_ADDR%
REMOTE_ADDR environment variable, is 3.15.202.4
%REMOTE_PORT%
REMOTE_PORT environment variable, is 31100
%REMOTE_USER%
REMOTE_USER environment variable, is
%INCLUDE{"page" ...}%
Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic"
The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic"
A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..."
A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE%
If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE%
If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC%
Table of Contents of current topic.
%TOC{"SomeTopic" ...}%
Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs.
required
topic="%TOPIC%"
The topic the search relates to
required
title="Title"
Text the is pre-pended to any search results
required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}%
Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #444444
[1] Note: The search form uses identical names for input fields.
[2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences.
Preferences Variables
Additional variables are defined in the preferences ( site-level ( SL ) in TWikiPreferences, web-level ( WL ) in WebPreferences of each web, and user level ( UL ) preferences in individual user topics):
Variable:
Level:
What:
%WIKIWEBMASTER%
SL
Webmaster email address (sender of email notifications) , is webmaster@netfrag.org
%WIKIWEBLIST%
SL
List of netfrag.org webs (in upper right corner of topics)
%WEBTOPICLIST%
WL
Common links of web (second line of topics)
%WEBCOPYRIGHT%
SL , WL
Copyright notice (bottom right corner of topics)
%WEBBGCOLOR%
WL
Background color of web
%NOSEARCHALL%
WL
Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR%
SL , UL
Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR%
SL , UL
Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH%
SL , UL
Horizontal size of edit box, is 100
%EDITBOXHEIGHT%
SL , UL
Vertical size of edit box, is 20
%RELEASEEDITLOCKCHECKBOX%
SL , UL
Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is: checked
%DONTNOTIFYCHECKBOX%
SL , UL
Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty. Value is: checked
%ATTACHLINKBOX%
SL , UL
Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is:
%HTTP_EQUIV_ON_VIEW%
SL
http-equiv meta tags for view, rdiff, attach, search* scripts.
%HTTP_EQUIV_ON_EDIT%
SL , UL
http-equiv meta tags for edit script.
%HTTP_EQUIV_ON_PREVIEW%
SL , UL
http-equiv meta tags for preview script.
%DENYWEBCHANGE%
WL
List of users and groups who are not allowed to change topics in the netfrag.org web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE%
WL
List of users and groups who are allowed to change topics in the netfrag.org web. (More in TWikiAccessControl)
%DENYTOPICCHANGE%
(any topic)
List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE%
(any topic)
List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME%
WL
List of users and groups who are not allowed to rename topics in the netfrag.org web. (More in TWikiAccessControl)
%ALLOWWEBRENAME%
WL
List of users and groups who are allowed to rename topics in the netfrag.org web. (More in TWikiAccessControl)
%DENYTOPICRENAME%
(any topic)
List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME%
(any topic)
List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES%
SL , WL
List of preferences that are not allowed to be overridden by next level preferences
Setting Preferences
The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line: [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value] Example:
Set VARIABLENAME = value
Creating Custom Variables
You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.
Example: Create a custom logo variable
To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif
Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file.
Attachments are stored under revision control, so uploads can never be lost, and files changes can be made with a rollback option that lets you retrieve all previous versions.
What Are Attachments Good For?
File Attachments can be used to create powerful groupware solutions - file sharing, document management - and for speedy Web authoring.
Document Management System
You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis? using; create a central reference library that's easy to access and manage by an entire user group.
File Sharing
For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!
Web Authoring
Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to embed on a page) and place them anywhere in on a single page, or for use across a web, or site-wide.
NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires server access, and may be more convenient if a large number of files, or a particular directory location, is required. These files can't be managed using browser-based Attachment controls.
Uploading Files
To upload: Click on the Attach link at the bottom of each page. A form is shown where you can browse for a file and upload it. The uploaded file will show up in the File Attachment table?.
Files of any type can be uploaded. Some files that might impose a security risk are renamed, ex: *.php files are renamed to *.php.txt.
Currently there is no file size limit besides the disk space on the server.
The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.
Downloading Files
To download: Click on the file in the File Attachment table?.
NOTE: There is no access control on individual attachments. If you need this type of control, create separate topics and define access restrictions per topic.
Moving Attachment Files
An attachement can be moved between topics. To do this click Action on the attachment to be moved. On the control page, select the new web and topic, the click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Deleting Attachments
It is not possible to delete attached files with the current TWiki implementation. However, they can be moved to another topic. You may care to have a topic Trash.TrashAttachments - move attachments that are no longer wanted here.
Linking to Attached Files
Once a file is attached it can be referenced in the topic. Example:
GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
Attach file: Smile.gif
Edit topic and write text: %ATTACHURL%/Smile.gif
Preview - text appears as , an image.
File Attachment Contents Table
Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.
Clicking on an Action link takes you to a new page that looks like this:
The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.
The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.
Known Issues
Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
TWiki Forms
Form-based input in topics, with name/value pairs stored as Meta Data variables; multiple forms per web & topic
Overview
By adding form-based input to free-form content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, the form appears in edit mode, and the contents are rendered as a table when viewing the actual page. When editing, can switch forms, if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.
Form Templates replace TWikiCategory Tables from the 01-Dec-2000 version of TWiki.
Main Changes from Category Tables
Form Templates more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.
Defining a Form Template
A Form Template is simply a page containing your form, defined in a table where each row is one form field.
Form Template Elements
form template - a set of fields defining a form (replaces category table definition)
A web can use one or more form templates.
form - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces category table)
A topic has zero or one of the defined forms. So there are topics with a form or without.
form field - a named item in a form (replaces category item name)
field type - selects the INPUT type:
select - drop-down menu or scrollable box
checkbox - one or more checkboxes
checkbox+buttons - one or more checkboxes, plus Set and Clear buttons
radio - one or more radio buttons
text - a one-line text field
textarea - a text box; size is 40x10 (columns x rows)
field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces category item value)
Defining a Form in One Topic
Create a new topic with your Form name: MyForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (see sample below).
For each field, fill in a new line; for the type of field, select from the list.
Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
The topic can be protected in the usual manner so that not everybody can change the form template - see TWikiAccessControl
[[...]] links can be used for force a link, at present [[...][...]] format is not supported.
The "Tooltip message" column is used as a tool tip for the field name (only if field name is a WikiName) - you only see the tooltip on edit.
The first item in the list is the default item. Alternative initial values can be given in a topic template such as WebTopicEditTemplate or using field=value or for checkboxes field=1.
The topic definition is not read when a topic is viewed.
Enabling Forms by Web
Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible Form Templates. Example:
Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.
A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.
Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:
other than checkboxes: name, ex: ?BugPriority=1
checkbox: namevalue=1, ex: ?ColourRed=1. Boxes with a tick must be specified.
Including Forms in New Topics
When you create a new topic in a web that has the WEBFORMS Preferences variable set, an Add Form button appears at the bottom of the page. You can start all new topics with forms enabled, and pre-select a form if there's more than one available:
Create a new topic to check - the Form should appear with values set.
Click Change to switch or remove Forms.
A form embedded in a topic also appears in a new topic. This is done by specifying the formtemplate parameter in the URL.
Setting Up Multiple Form Options
The optional WEBFORMS variable defines alternative Form Templates that can be selected by pressing Change in edit mode.
A Template topic can use any Form Template.
New topics with a Form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports - a SubmitVacationRequest topic and so on. These can specify the required template topic with its associated Form.
Form Template Data Storage
The Form Template topic name, fields and values are stored as TWikiMetaData. The order of field/value pairs in the Meta Data is the same as in the Template.
-- JohnTalintyre - 16 Aug 2001
-- MikeMannix? - 03 Dec 2001
TWiki Templates
Definition of the templates used to render all HTML pages displayed in TWiki
Overview
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML mark-up for template-specific content. Templates are used to define page layout?, and also to supplydefault content? for new pages.
Major changes from the previous template system
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
separates a set of common template parts into a base template that is included by all of the related templates;
defines common variables, like a standard separator (ex: "|"), in the base template;
defines variable text in the individual templates and passes it back to the base template.
Functional Specifications
Special template directives (or preprocessor commands) are embedded in normal templates.
Use of template directives is optional, templates work without them.
All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
Directives:
%TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
%TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
%TMPL:END%: Ends variable definition.
%TMPL:P{"var"}%: Prints a previously defined variable.
Variables are live in a global name space, there is no parameter passing.
Two-pass processing, so that you can use a variable before declaring it or after.
Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
NOTE: The template directives work only for templates, they do not get processed in topic text.
TWiki Master Template
All common parts are defined in a master template, twiki.tmpl, that all other templates use.
Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%
Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}%
Skeleton of oops dialog
Types of Template
There are two types of templates:
HTML Page Templates: Defines layout of netfrag.org pages
Template Topics: Defines default text when you create a new topic
HTML Page Templates
netfrag.org uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.
The template files are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded per web. The following search order applies:
twiki/templates/$webName/$scriptName.tmpl
twiki/templates/$scriptName.tmpl
Note:$webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).
Note:TWikiSkins can be defined to overload the standard templates.
Special variables are used in templates, especially in view, to display meta data.
Template Topics
Template topics define the default text for new topics. There are three types of template topics:
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. The following search order applies when you create a new topic:
The topic name specified by the templatetopic CGI parameter.
WebTopicEditTemplate in the current web.
WebTopicEditTemplate in the TWiki web.
Template Topics in Action
Here is an example for creating new topics based on a specific template topic:
Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="submit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
The "onlywikiname" parameter enforces WikiWords for topic names.
Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is: -- %WIKIUSERNAME% - %DATE%
Templates by Example
Attached is an example of an oops base template oopsbase.tmpl and a example oops dialog oopstest.tmpl which is based on the base template. NOTE: This isn't the release version, just a quick, simple demo.
Base template oopsbase.tmpl
The first line declares the delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%
Each oops template basically just defines some variables and includes the base template that does the layout work.
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
* Some more blah blah blah blah blah blah blah blah blah blah...
* Param1: %PARAM1%
* Param2: %PARAM2%
* Param3: %PARAM3%
* Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%
Sample screen shot of oopstest.tmpl
With URL: .../bin/oops/Test/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
Known Issues
A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template is a structurally complete HTML document with a .tmpl filename extension - it contains unresolved %VARIABLES%, but can still be previewed directly in a browser.
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
Overview
Skins are customized TWikiTemplates files. You can use skins to change the look of a netfrag.org topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.
Defining Skins
Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.
The ?skin=name URL parameter overrides the SKIN Preference value.
-- PeterThoeny - 14 Jul 2001
TWiki Formatted Search Results
Inline search feature allows flexible formatting of search result
Overview
By default, the format for displaying a search result is fixed, e.g. a table with rows of topic name and topic summary. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (i.e. %SEARCH{ "food" format="| $topic | $summary |" }%).
Syntax
Two paramters can be used to specify a customized search result:
1. header="..." parameter
Use the header paramter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. I.e. header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format paramter to specify the format of one search hit. I.e. format="| $topic | $summary |"
Variables that can be used in the format string:
Time stamp of last topic update, i.e. 27 Apr 2024 - 10:56
$isodate
Time stamp of last topic update, i.e. 2024-04-27T10:56Z
$rev
Number of last topic revision, i.e. 1.4
$wikiusername
Wiki user name of last topic update, i.e. Main.JohnSmith
$username
User name of last topic update, i.e. JohnSmith
$summary
Topic summary
$formfield(name)
The field value of a form field, i.e. $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$pattern(reg-exp)
A regular expression pattern to extract some text from a topic, i.e. $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, i.e. $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised, i.e. if you include a table make sure to include everything including the table end tag.
Examples
Bullet list showing topic name and summary
Write this:
%SEARCH{ "FAQ" scope="topic" nosearch="on" nototal="on" header=" * *Topic: Summary:*" format=" * [[$topic]]: $summary" }%
To get this:
Topic: Summary:
TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Table showing form field values of topics with a form
Write this in the Know web:
| *Topic:* | *OperatingSystem:* | *OsVersion:* | %SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs
Overview
TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
Meta Data Syntax
Format is the same as in TWikiVariables, except all fields have a key.
%META:<type>{key1="value1" key2="value2" ...}%
Order of fields within the meta variables is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the variables themselves is defined).
Each meta variable is on one line.
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Meta Data Specifications
The current version of Meta Data is 1.0, with support for the following variables.
Format of this topic, will be used for automatic format conversion
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed.
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
form fields remain in the order they are defined
the diff function output appears in a logical order
The recommended sequence is:
META:TOPICINFO
text of topic
META:TOPICMOVED (optional)
META:TOPICPARENT (optional)
META:FILEATTACHMENT (0 or more entries)
META:FORM (optional)
META:FIELD (0 or more entries; FORM required)
Viewing Meta Data in Page Source
When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic
Rendering Meta Data
Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.
Current support covers:
Prefix for parents, only if there are parents; default ""
suffix="..."
Suffix, only appears if there are parents; default ""
separator="..."
Separator between parents, default is " > "
Known Issues
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.
-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001
TWiki Plugins
Plug-in enhanced feature add-ons, with a Plugin API for developers
Overview
You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:
add virtually unlimited features while keeping the main TWiki code compact and efficient;
heavily customize an installation and still do clean updates to new versions of TWiki;
rapidly develop new TWiki functions in Perl using the Plugin API.
Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.
Preinstalled Plugins
TWiki comes with three Plugins as part of the standard installation.
DefaultPlugin optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules? for simple custom processing.)
EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.
InterwikiPlugin is preinstalled but can be disabled or removed. Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own.
Installing Plugins
Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.
Most Plugins can be installed in three easy steps, with no programming skills required:
Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
Check the demo example on the Plugin topic: if it's working, the installation was fine!
Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.
Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.
Doc page: Read all available info about the Plugin; download the attached distribution files.
Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.
On-Site Pretesting
To test new Plugins on your installation before making them public, you may want to use one of these two approaches:
Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
Test Plugins and other new features in the Test installation until you're satisfied.
If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.
Method 2: List the Plugin under Test in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Test web and do the testing there.
Managing Plugins
When you finish installing a Plugin?, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.
Setting Preferences
Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
All Plugin modules present in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the netfrag.org web for the Plugin topics. Settings in TWikiPreferences are:
Set INSTALLEDPLUGINS = DefaultPlugin, ...
Set DISABLEDPLUGINS = EmptyPlugin, ...
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
Set SHORTDESCRIPTION = Blah blah woof woof.
Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
Set DEBUG = 0
The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
Listing Active Plugins
Plugin status variables let you list all active Plugins wherever needed. There are two list formats:
The %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
HeadlinesPlugin: Build news portals that show headline news based on RSS news feeds from news sites.
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
TablePlugin: Control attributes of tables and sorting of table columns
VisualConfirmPlugin: Plugin for visual confirmation of new user registration.
The TWiki Plugin API
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
Available Core Functions
The lib/TWiki/Func.pm implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
If you use functions not in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.
Predefined Hooks
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.
Plugin Version Detection
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
All modules require a $VERSION='0.000' variable, beginning at 1.000.
The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).
With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API? Plugins by providing a programming interface for TWiki.
The DefaultPlugin Alternative
DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.
Anatomy of a Plugin
A basic TWiki Plugin consists of two elements:
a Perl module, ex: MyFirstPlugin.pm
a documentation topic, ex: MyFirstPlugin.txt
The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call.
In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API?, you're ready to develop Plugins.
Creating the Perl Module
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API? specs for more information.
Writing the Documentation Topic
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package?.) To create a documentation topic:
Copy the Plugin topic template from EmptyPlugin. To copy the text, go to the page and:
click Edit
select all in the Edit box & copy
Cancel the edit
paste & save as a text file or new topic on your site
Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
Save your topic as a text file, for use in packaging? and publishing? your Plugin.
OUTLINE: Doc Topic Contents
Check EmptyPlugin on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:
Syntax Rules: <Describe any special text formatting that will be rendered.>"
MyFirstPlugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
Plugins Preferences <If user settings are needed, explain... Entering valuse works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
Set <EXAMPLE = value added>
How-to Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"
Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>"
Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Packaging for Distribution
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
Publishing for Public Use
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
Post the Plugin documentation topic in the TWiki:Plugins web:
create a new topic using the Plugin name, ex: MyFirstPlugin.txt
paste in the topic text from Creating Plugin Documentation? and save
Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
Utilities for searching, navigation, and monitoring site activity
Overview
TWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to email alerts when topics are edited, and WebStats, to generate detailed activity reports.
WebNotify Recent Changes Alert
Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a deamon in regular intervals. The script sends an automated email to subscribed users if topics were changed in a web within last interval.
netfrag.org will use the Net::SMTP module if it is installed on your system. Set this with the SMTPMAILHOST variable in TWikiPreferences.
You can use an external mail program, like sendmail, if the Net::SMTP module is not installed. Set the program path in $mailProgram in TWiki.cfg.
Net::SMTP can be easily disabled (ex: if there is an installation error) by setting SMTPMAILHOST in TWikiPreferences to an empty value.
You can set a separate SMTPSENDERHOST variable to define the mail sender host (some SMTP installations require this).
Setting the Automatic Email Schedule
For Unix platforms: Edit the cron table so that mailnotify is called in an interval of your choice. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:
The above line will call mailnotify at 15 minutes and 45 minutes past every hour. The -q switch suppresses all normal output.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows NT/2000: You can use a scheduled task if you have administrative privileges.
Note: AT on an NT machine is pretty limited.
Microsoft lists several third-party
replacements
(as of 2001-11-20, none of them free).
WebStatistics Site Usage Log
You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.
You can automatically generate usage statistics for all webs. To enable this:
Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in TWiki.cfg are set. This will generate log entries in file twiki/data/log<date>.txt .
The WebStatistics topic must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry: 0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example: 0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
Generating Statistics Manually by URL
The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
Update current month for all webs: http://mydomain.com/twiki/bin/statistics
Update current month for Main web only: http://mydomain.com/twiki/bin/statistics/Main
Update January 2000 for Main web: http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
WebSearch
WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:
topic title or full-text search
regular expressions
search within web or site-wide
index-style A-Z alphabetical listing sorted topic title
many more
See also: TWikiVariables for including hard-coded searches in text.
WebChanges
To check for the most recently edited topics while on-site, use the WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.
This is simply a preset SEARCH. The number of topics listed by the limit parameter.:
Browser-based rename, move, and delete for individual topics
Overview
Use browser controls while viewing a topic, to change its name, move it to another TWiki web, or delete it to a hidden Trash web.
How to Rename/Move/Delete a Topic
Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move].
Select target web if other than the current web - chose Trash to delete a topic?
Enter the new topic name - default is current name NOTE: You will be warned if there are locks or if there is a name conflict.
Select from the list of referring links any topics NOT to be updated with the new name (by default, all referring links will be updated).
Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
If any of the referring pages are locked then they will be listed.
You can correct these later by again pressing [Rename/Move].
Referring Topics
Referring topics are found using the the %SEARCH% variable, see the template searchrenameview.tmpl. First, matching topics in the current Web are listed - matches are to topic. Next, all Webs (including the current one) are listed that match web.topic. Because %SEARCH% is used, Webs marked in WebPreferences as NOSEARCHALL will not show up in the search for refernces to the topic being changed.
Changed references are kept are as short as possible, ex: topic is used in preference to web.topic.
About Deleting a Topic
Deleted topics are moved to the Trash web - NOT physically erased from the server. All webs share Trash - in case of a name conflict with a topic already Trash, the user is alerted and asked to choose a new name.
Clearing the Trash
The Trash web should be be cleared periodically, by archiving the contents if required (recommended), then deleting the files from the Trash directory.
%<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%"
title="This topic used to exist and was moved to: "}%
Effect of Access Settings
Permissions affect the rename function in various ways. To rename a topic, you need both change and rename permissions. To alter refer4ing topics, you need change permission. See TWikiAccessControl for information on setting up access permissions.
How Rename/move Works
%SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
User can omit one or more topics from the update list.
<pre> and <verbatim> are honoured - no changes are made to text within these areas.
The topic is moved (if locks allow).
References are changed (locks and permissions permitting).
Any referring topics that can't be changed due to locks are listed - user can change them at another time.
Known Limitations
Rename/move in is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that search can show matches that will not be updated because of case differences. Other mismatches to actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]]
[[old topic]] => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]] => [[NewTopic]]
Adding, renaming and deleting webs are manual operations done directly on the server
Overview
Managing TWiki webs requires direct access to the installation files on the host server. There are currently no browser-based equivalents of the Rename/move/delete topic tools for working with webs.
Adding a New Web
Adding new webs is quick and easy - you can have a basic web up and running in a couple of minutes:
Create a new directory under twiki/data/, ex: twiki/data/Newweb
the name has to start with a capital and cannot be a WikiWord
NOTE: If you plan to rename the netfrag.org.Main web, remember that TWiki stores user and group topics in %MAINWEB%, default named Main. That means, every WikiName signature - Main.SomeUserName - points to it and would need updating (unless the variable, %MAINWEB%.SomeUserName, is used throughout).
Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic.
Make changes as required, to Newwebname.SomeTopic or better yet, to %MAINWEB%.SomeTopic.
Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable.
Edit the TWikiWebsTable topic: Rename or delete the web from the table.
Login to the netfrag.org server, via Telnet or FTP.
Go to twiki/data and rename or remove the web directory.
Go to twiki/templates and rename or remove the web directory if present.
Go to twiki/pub and rename or remove the web directory if present.
Annotated listings of files included in the 01-Sep-2001 TWiki distribution
Overview
This Appendix contains directory and file listings, and individual file descriptions, for the full 01-Sep-2001 TWiki distribution package.
Directory Structure
You can rename the root TWiki directory - twiki - to whatever you like by changing it in the twiki.cfg configuration file. However, to keep the current installation and future upgrades simple, you should leave the subdirectory structure intact:
Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Plugins/DefaultPlugin.pm
Handles some legacy rules
TWiki/Plugins/EmptyPlugin.pm
Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm
Use aliases as links for predefined URLs
Files under twiki/pub
The pub directory stores data-related files, including images used by TWiki and FileAttachments. Attachments are stored in sub-directories created with the related topic name. Partial file list:
TWiki page data stored as individual text files. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - Main, TWiki, Know, Test - with documentation and demo content, a Trash web, and a _default directory containing all topics required to start a new web. Partial file list:
Displays WebChanges list of recently changed topics
edit.iejs.tmpl
Edit window with IE specific JavaScript
edit.tmpl
Main edit window
mailnotify.tmpl
Email notification
moveattachment.tmpl
Control screen
oopsaccesschange.tmpl
Error message
oopsaccessgroup.tmpl
Error message
oopsaccessrename.tmpl
Error message
oopsaccessview.tmpl
Error message
oopsauth.tmpl
Error message
oopsbadpwformat.tmpl
Error message
oopschangepasswd.tmpl
Error message
oopsempty.tmpl
Error message
oopslocked.tmpl
Error message
oopslockedrename.tmpl
Error message
oopsmissing.tmpl
Error message
oopsmore.tmpl
More topic actions message
oopsmoveerr.tmpl
Error message
oopsnoformdef.tmpl
Error message
oopsnotwikiuser.tmpl
Error message
oopsnoweb.tmpl
Error message
oopspreview.tmpl
Error message
oopsregexist.tmpl
Error message
oopsregpasswd.tmpl
Error message
oopsregrequ.tmpl
Error message
oopsregthanks.tmpl
Error message
oopsregwiki.tmpl
Error message
oopsrenameerr.tmpl
Error message
oopsresetpasswd.tmpl
Error message
oopsrev.tmpl
Error message
oopssave.tmpl
Error message
oopssaveerr.tmpl
Error message
oopssendmailerr.tmpl
Error message
oopstopicexists.tmpl
Error message
oopsupload.tmpl
Error message
oopswrongpassword.tmpl
Error message
preview.tmpl
Preview Changes screen
rdiff.tmpl
Displays text changes before & after (Diffs)
register.tmpl
Registration page
registernotify.tmpl
Registration notification
rename.tmpl
Doing a new topic rename, user chooses web & topic
renamebase.tmpl
Used by other rename templates
renameconfirm.tmpl
Confirms a pre-specified rename, ex: undoing a rename
renamerefs.tmpl
Rename done, but some references not changed (topics were locked)
search.tmpl
Search screen
searchbookview.tmpl
Search results with full topic content
searchmeta.tmpl
Search screen
searchrenameview.tmpl
Used by rename to list references to topic being renamed
twiki.tmpl
Base template definitions used by other templates
view.plain.tmpl
Printable topic view with reduced header/footer
view.print.tmpl
Topic view without header/footer
view.tmpl
Main topic view
TWiki File System Snapshot
The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.
Directory twiki/bin:
New topic templates as topics instead of templates. Customize by editing the topic. Retired notedited.tmpl, notext.tmpl and notwiki.tmpl templates. More in TWikiTemplates.
The table syntax has been enhanced to (i) render | *bold* | cells as table headers, (ii) render space padded cells | center aligned | and | right aligned |, (iii) span multiple columns using | empty cells |||. More in TextFormattingRules.
Security fix Questionable files like PHP scripts (executables) and .htaccess files that are attached to a topic get a .txt suffix appended to the file name. See also TWiki:Codev/FileAttachmentFilterSecurityAlert
New Wiki rule to specify arbitrary text for external links (i.e. [[http://TWki.org][TWiki]]) and internal links (i.e [[WikiSyntax][syntax]]). More in TWikiVariables.
New Wiki rule for named anchors, e.g. links within a topic. Define a named anchor with #MyAnchor at the beginning of a line, and link to it with [[#MyAnchor]]. More in TWikiVariables.
Format changed of %GMTIME{"..."}% and %SERVERTIME{"..."}% variables. Format is now "$hour:$min" instead of "hour:min". More in TWikiVariables. Attention: Check your existing topics when you upgrade TWiki!
WebChanges, WebSearch and e-mail notification indicate also the revision number of a topic (i.e. 18 Jan 2001 16:43 r1.5), or NEW for a new topic (i.e. i.e. 18 Jan 2001 16:43 NEW).
TWiki skins Define a different page layout with a customized header and footer layout, i.e. a print skin for a printable view of a topic. More in TWikiSkins and TWiki:Codev/TWikiSkins.
Improved include handling. Infinite recursion of includes are prevented; new variables %BASEWEB%, %INCLUDINGWEB%, %BASETOPIC% and %INCLUDINGTOPIC% to have more control over include handling. More in TWikiVariables and TWiki:Codev/IncludeHandlingImprovements.
New TWikiPreferences variables %HTTP_EQUIV_ON_VIEW% , %HTTP_EQUIV_ON_EDIT% and %HTTP_EQUIV_ON_PREVIEW% that define the <meta http-equiv="..."> meta tags for the TWiki templates. This can be used for example to set a document expiration time.
More forgiving syntax for *bold*, italic, __bold italic__ and fixed , where it is not necessary anymore to have a trailing space before .,;:?! characters.
Advanced search features like search multiple webs; sort by topic name / modified time / author; limit the number of results returned. More in TWikiVariables.
Uploading a file (topic file attachment) will optionally create a link to the uploaded file at the end of the topic. The preference variable %ATTACHLINKBOX% controls the default state of the link check box in the attach file page.
Edit preferences topics to set TWiki variables. There are three level of preferences Site-level (TWikiPreferences), web-level (WebPreferences in each web) and user-level preferences (for each of the TWikiUsers). With this, discontinue use of server side include of wikiwebs.inc , wikiwebtable.inc , weblist.inc , webcopyright.inc and webcolors.inc files.
New variable %SCRIPTSUFFIX% / $scriptSuffix containing an optional file extension of the TWiki Perl script. Templates have been changed to use this variable. This allows you to rename the Perl script files to have a file extension like for example ".cgi".
New variable %SCRIPTURLPATH% / $scriptUrlPath containing the script URL without the domain name. Templates have been changed to use this variable instead of %SCRIPTURL% . This is for performance reasons.
Changed the syntax for server side include variable from %INCLUDE:"filename.ext"% to %INCLUDE{"filename.ext"}% . (Previous syntax still supported. Change was done because of inline search syntax)
Inline search. New variable %SEARCH{"str" ...}% to show a search result embedded in a topic text. TWikiVariables has more on the syntax. Inline search combined with the category table feature can be used for example to create a simple bug tracking system.
Access statistics. Each web has a WebStatistics topic that shows monthy statistics with number of topic views and changes, most popular topics, and top contributors. (It needs to be enabled, TWikiDocumentation has more.)
Fixed bug where TWiki would not initialize correctly under certain circumstances, i.e. when running it under mod_perl. Sub initialize in wiki.pm did not handle $thePathInfo correctly.
Fixed bug where an email address starting with a WikiName was rendered as an internal Wiki link instead of an email address, i.e. SomeWikiName@somewhere.test .
Limit the number of revisions shown at the bottom of the topic. Example Topic TWikiHistory . { ..... Diffs r1.10 >r1.9>r1.8>r1.7>... } Additional revisions can be selected by pressing the >... link.
New text formatting rule for creating tables. Text gets rendered as a table if enclosed in " " vertical bars. Example line as it is written and how it shows up
Flag $doRemovePortNumber in wikicfg.pm to optionally remove the port number from the TWiki URL. Example www.some.domain:1234/twiki gets www.some.domain/twiki .
Search path for include files in %INCLUDE:"file.inc"% variable. Search first in the current web, then in parent data directory. Useful to overload default include text in the data directory by web-specific text, like for example webcopyright.inc text.
Link a plural topic to a singular topic in case the plural topic does not exist. Example TestVersion / TestVersions , TestPolicy / TestPolicies , TestAddress / TestAddresses , TestBox / TestBoxes .
Separate wiki.pm into configuration (wikicfg.pm) and TWiki core (wiki.pm) . This is to ease the upgrade of TWiki installations, it also allows customized extensions to TWiki without affecting the TWiki core.
New text formatting rule for creating fixed font text . Words get showns in fixed font by enclosing them in "=" equal signs. Example Writing =fixed font= will show up as fixed font .
Possible to view complete revision history of a topic on one page. Access at the linked date in the Changes page, or the Diffs link at the bottom of each topic, e.g. Topic TWikiHistory . { Edit Ref-By Diffs r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Possible to add a category table to a TWiki topic. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. TWikiDocumentation has more on setup. The TWiki.Know web uses this category table to set classification, platform and OS version.
Internal log of topic save actions to the file data/logYYYYMM.txt, where YYYYMM the year and month in numeric format is. Intended for auditing only, not accessible from the web.
The email notification and the Changes topic have now a topic date that is linked. Clicking on the link will show the difference between the two most recent topic revisions.
View differences between topic revisions. Each topic has a list of revisions (e.g. r1.3) and differences thereof (e.g. >) at the bottom Topic TWikiHistory . { Edit Ref-By r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Added revision control using RCS. Each topic has now a list of revisions at the bottom and a revision info, e.g. Topic TWikiHistory . { Edit Ref-By r1.3 r1.2 r1.1 } Revision r1.3 1998/10/26 01:34:00 by PeterThoeny
Refered-By Find out which topics have a link to the current topic. Each topic has a Ref-By link for that. Note Only references from the current web are shown, not references from other webs.
Topic WebChanges shows Wiki username instead of Intranet username, e.g. PeterThoeny instead of thoeny in case the Wiki username exists. Implementation Automatic lookup of Wiki username in topic TWikiUsers.
FAQ: How do I delete or rename a topic? Answer: New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously ...
FAQ: Why does the topic revision not increase when I edit a topic? Answer: The same topic revision will be used when you save a topic again within a certain time ...
FAQ: TWiki has a GPL (GNU General Public License). What is GPL? Answer: TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of ...
FAQ: I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer: That is an indication ...
FAQ: What happens if two of us try to edit the same topic simultaneously? Answer: The second person gets a warning that the topic is currently being edited by another ...
FAQ: I would like to install TWiki on my server. Can I get the source? Answer: TWiki is distributed under the GnuGeneralPublicLicense. You can request the source ...
FAQ: So what is this WikiWiki thing exactly? Answer: A set of pages of information that are open and free for anyone to edit as they wish. They are stored on a server ...
FAQ: Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer: TWiki is one of many WikiWikiClones, the first one was built by Ward Cummingham ...
Form-based input in topics, with name/value pairs stored as Meta Data variables; multiple forms per web & topic
Overview
By adding form-based input to free-form content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, the form appears in edit mode, and the contents are rendered as a table when viewing the actual page. When editing, can switch forms, if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.
Form Templates replace TWikiCategory Tables from the 01-Dec-2000 version of TWiki.
Main Changes from Category Tables
Form Templates more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.
Defining a Form Template
A Form Template is simply a page containing your form, defined in a table where each row is one form field.
Form Template Elements
form template - a set of fields defining a form (replaces category table definition)
A web can use one or more form templates.
form - A topic containing additional meta-data (besides the free form TEXTAREA) which categorizes the content. (replaces category table)
A topic has zero or one of the defined forms. So there are topics with a form or without.
form field - a named item in a form (replaces category item name)
field type - selects the INPUT type:
select - drop-down menu or scrollable box
checkbox - one or more checkboxes
checkbox+buttons - one or more checkboxes, plus Set and Clear buttons
radio - one or more radio buttons
text - a one-line text field
textarea - a text box; size is 40x10 (columns x rows)
field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces category item value)
Defining a Form in One Topic
Create a new topic with your Form name: MyForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
Create a TWiki table, with each column representing one element of an entry field: Name, Type, Size, Values, and Tooltip msessage (see sample below).
For each field, fill in a new line; for the type of field, select from the list.
Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
The topic can be protected in the usual manner so that not everybody can change the form template - see TWikiAccessControl
[[...]] links can be used for force a link, at present [[...][...]] format is not supported.
The "Tooltip message" column is used as a tool tip for the field name (only if field name is a WikiName) - you only see the tooltip on edit.
The first item in the list is the default item. Alternative initial values can be given in a topic template such as WebTopicEditTemplate or using field=value or for checkboxes field=1.
The topic definition is not read when a topic is viewed.
Enabling Forms by Web
Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible Form Templates. Example:
Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.
A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.
Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:
other than checkboxes: name, ex: ?BugPriority=1
checkbox: namevalue=1, ex: ?ColourRed=1. Boxes with a tick must be specified.
Including Forms in New Topics
When you create a new topic in a web that has the WEBFORMS Preferences variable set, an Add Form button appears at the bottom of the page. You can start all new topics with forms enabled, and pre-select a form if there's more than one available:
Create a new topic to check - the Form should appear with values set.
Click Change to switch or remove Forms.
A form embedded in a topic also appears in a new topic. This is done by specifying the formtemplate parameter in the URL.
Setting Up Multiple Form Options
The optional WEBFORMS variable defines alternative Form Templates that can be selected by pressing Change in edit mode.
A Template topic can use any Form Template.
New topics with a Form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports - a SubmitVacationRequest topic and so on. These can specify the required template topic with its associated Form.
Form Template Data Storage
The Form Template topic name, fields and values are stored as TWikiMetaData. The order of field/value pairs in the Meta Data is the same as in the Template.
-- JohnTalintyre - 16 Aug 2001
-- MikeMannix? - 03 Dec 2001
TWiki uses a handful of general computer and Internet terms in a TWiki-specific way. This could get confusing, but it actually works out fine in use. The TWikiGlossary is also a quick way to get familiar with the overall TWiki set-up...
(Under...construction: this is a rough draft)AttachmentakaFile Attachment - upload files by browser and attach them to any page, where they can be viewed, edited, downloaded; accessed by clicking Attach at page bottom (FileAttachments)
Plugin - a TWiki feature add-on; a Perl module that enhances TWiki, through the Plugin API spec; named <_>Plugin.pm, ex: SomePlugin.pm (TWikiPlugins)
Plugin API - specs for building TWiki Plugins with Perl modules (TWikiPlugins)
Preference - a customizable TWiki parameter; settings site-wide, by the web, by the topic on TWikiPreferences and WebPreferences pages, also on Plugins, user and regular topic pages.
site - a TWiki installation consisting of one or more TWiki webs?topicakaWikiTopic - a single TWiki page, it has a WikiName that's unique within its home web?TWiki - based on "Wiki", from the original WikiWikiWeb, first OF this style of edit-anything-anywhere Web environment; by chance, also the name of a robot (as in, the robo-head in the TWiki logo) in the old Buck Rogers TV series (TWikiSite)
TWiki.org (twiki.org) - official home site, center of all development, housed on SourceForge.com
variable - text-strings of the form %VARIABLE% that are expanded on the fly into text, image, or any other type of embedded content; predefined variables are coded into the main TWiki package, Plugins variables, and user-specified variables are created in TWikiPreferences, WebPreferences, or single topics
web - with a small "w", as opposed to the Web, World Wide; a collection of TWiki topics under a common name; topics share Preference settings, disk file structure, and are handled as a group by search
WikiTopic - see: topic?
-- MikeMannix? - 09 Sep 2001
New topic templates as topics instead of templates. Customize by editing the topic. Retired notedited.tmpl, notext.tmpl and notwiki.tmpl templates. More in TWikiTemplates.
The table syntax has been enhanced to (i) render | *bold* | cells as table headers, (ii) render space padded cells | center aligned | and | right aligned |, (iii) span multiple columns using | empty cells |||. More in TextFormattingRules.
Security fix Questionable files like PHP scripts (executables) and .htaccess files that are attached to a topic get a .txt suffix appended to the file name. See also TWiki:Codev/FileAttachmentFilterSecurityAlert
New Wiki rule to specify arbitrary text for external links (i.e. [[http://TWki.org][TWiki]]) and internal links (i.e [[WikiSyntax][syntax]]). More in TWikiVariables.
New Wiki rule for named anchors, e.g. links within a topic. Define a named anchor with #MyAnchor at the beginning of a line, and link to it with [[#MyAnchor]]. More in TWikiVariables.
Format changed of %GMTIME{"..."}% and %SERVERTIME{"..."}% variables. Format is now "$hour:$min" instead of "hour:min". More in TWikiVariables. Attention: Check your existing topics when you upgrade TWiki!
WebChanges, WebSearch and e-mail notification indicate also the revision number of a topic (i.e. 18 Jan 2001 16:43 r1.5), or NEW for a new topic (i.e. i.e. 18 Jan 2001 16:43 NEW).
TWiki skins Define a different page layout with a customized header and footer layout, i.e. a print skin for a printable view of a topic. More in TWikiSkins and TWiki:Codev/TWikiSkins.
Improved include handling. Infinite recursion of includes are prevented; new variables %BASEWEB%, %INCLUDINGWEB%, %BASETOPIC% and %INCLUDINGTOPIC% to have more control over include handling. More in TWikiVariables and TWiki:Codev/IncludeHandlingImprovements.
New TWikiPreferences variables %HTTP_EQUIV_ON_VIEW% , %HTTP_EQUIV_ON_EDIT% and %HTTP_EQUIV_ON_PREVIEW% that define the <meta http-equiv="..."> meta tags for the TWiki templates. This can be used for example to set a document expiration time.
More forgiving syntax for *bold*, italic, __bold italic__ and fixed , where it is not necessary anymore to have a trailing space before .,;:?! characters.
Advanced search features like search multiple webs; sort by topic name / modified time / author; limit the number of results returned. More in TWikiVariables.
Uploading a file (topic file attachment) will optionally create a link to the uploaded file at the end of the topic. The preference variable %ATTACHLINKBOX% controls the default state of the link check box in the attach file page.
Edit preferences topics to set TWiki variables. There are three level of preferences Site-level (TWikiPreferences), web-level (WebPreferences in each web) and user-level preferences (for each of the TWikiUsers). With this, discontinue use of server side include of wikiwebs.inc , wikiwebtable.inc , weblist.inc , webcopyright.inc and webcolors.inc files.
New variable %SCRIPTSUFFIX% / $scriptSuffix containing an optional file extension of the TWiki Perl script. Templates have been changed to use this variable. This allows you to rename the Perl script files to have a file extension like for example ".cgi".
New variable %SCRIPTURLPATH% / $scriptUrlPath containing the script URL without the domain name. Templates have been changed to use this variable instead of %SCRIPTURL% . This is for performance reasons.
Changed the syntax for server side include variable from %INCLUDE:"filename.ext"% to %INCLUDE{"filename.ext"}% . (Previous syntax still supported. Change was done because of inline search syntax)
Inline search. New variable %SEARCH{"str" ...}% to show a search result embedded in a topic text. TWikiVariables has more on the syntax. Inline search combined with the category table feature can be used for example to create a simple bug tracking system.
Access statistics. Each web has a WebStatistics topic that shows monthy statistics with number of topic views and changes, most popular topics, and top contributors. (It needs to be enabled, TWikiDocumentation has more.)
Fixed bug where TWiki would not initialize correctly under certain circumstances, i.e. when running it under mod_perl. Sub initialize in wiki.pm did not handle $thePathInfo correctly.
Fixed bug where an email address starting with a WikiName was rendered as an internal Wiki link instead of an email address, i.e. SomeWikiName@somewhere.test .
Limit the number of revisions shown at the bottom of the topic. Example Topic TWikiHistory . { ..... Diffs r1.10 >r1.9>r1.8>r1.7>... } Additional revisions can be selected by pressing the >... link.
New text formatting rule for creating tables. Text gets rendered as a table if enclosed in " " vertical bars. Example line as it is written and how it shows up
Flag $doRemovePortNumber in wikicfg.pm to optionally remove the port number from the TWiki URL. Example www.some.domain:1234/twiki gets www.some.domain/twiki .
Search path for include files in %INCLUDE:"file.inc"% variable. Search first in the current web, then in parent data directory. Useful to overload default include text in the data directory by web-specific text, like for example webcopyright.inc text.
Link a plural topic to a singular topic in case the plural topic does not exist. Example TestVersion / TestVersions , TestPolicy / TestPolicies , TestAddress / TestAddresses , TestBox / TestBoxes .
Separate wiki.pm into configuration (wikicfg.pm) and TWiki core (wiki.pm) . This is to ease the upgrade of TWiki installations, it also allows customized extensions to TWiki without affecting the TWiki core.
New text formatting rule for creating fixed font text . Words get showns in fixed font by enclosing them in "=" equal signs. Example Writing =fixed font= will show up as fixed font .
Possible to view complete revision history of a topic on one page. Access at the linked date in the Changes page, or the Diffs link at the bottom of each topic, e.g. Topic TWikiHistory . { Edit Ref-By Diffs r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Possible to add a category table to a TWiki topic. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. TWikiDocumentation has more on setup. The TWiki.Know web uses this category table to set classification, platform and OS version.
Internal log of topic save actions to the file data/logYYYYMM.txt, where YYYYMM the year and month in numeric format is. Intended for auditing only, not accessible from the web.
The email notification and the Changes topic have now a topic date that is linked. Clicking on the link will show the difference between the two most recent topic revisions.
View differences between topic revisions. Each topic has a list of revisions (e.g. r1.3) and differences thereof (e.g. >) at the bottom Topic TWikiHistory . { Edit Ref-By r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Added revision control using RCS. Each topic has now a list of revisions at the bottom and a revision info, e.g. Topic TWikiHistory . { Edit Ref-By r1.3 r1.2 r1.1 } Revision r1.3 1998/10/26 01:34:00 by PeterThoeny
Refered-By Find out which topics have a link to the current topic. Each topic has a Ref-By link for that. Note Only references from the current web are shown, not references from other webs.
Topic WebChanges shows Wiki username instead of Intranet username, e.g. PeterThoeny instead of thoeny in case the Wiki username exists. Implementation Automatic lookup of Wiki username in topic TWikiUsers.
Server and client system requirements for TWiki 01-Sep-2001
Overview
Maintaining minimum client and server requirements is necessary to keep TWiki deployment as broad as possible.
Server Requirements
TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements:
Required Server Environment
Resource
Unix
Windows
Perl
5.005_03 or higher
Non standard Perl modules
Net::SMTP (or sendmail)
Net::SMTP, MIME::Base64, Digest::SHA1
RCS
5.7 or higher
Other external programs
ls, fgrep, egrep
Web server
Apache; others (with support for CGI, authentication, extended path) *
Current documentation covers Linux only. A TWikiOnWindows installation guide is next.
generates XHTML 1.0 pages that are compatible with HTML 3.2
minimal use of JavaScript in the user interface (degrades gracefully)
no cookies
no CSS
You can easily add capabilities, through customizing the templates, for one, while tailoring the browser requirements to your situation.
Known Issues
The new TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything: browser-specific functions, stylesheets (CSS), DHTML, Java applets, cookies.
Installation instructions for the TWiki 01-Sep-2001 production release
Overview
These installation steps are based on the Apache Web server on Linux. TWiki runs on other Web servers and Unix systems, and should be fine with any OS and server that meet the system requirements. Documentation for other platforms is currently limited. For Windows, check TWiki:Codev/TWikiOnWindows. Search the TWiki:Codev web for other intallation notes.
Standard Installation
Request and download the TWiki 01-Sep-2001 distribution in Unix ZIP format from http://TWiki.org/download.html. (To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/SourceForgeHowTo.)
Step 1: Create & Configure the Directories
NOTE:If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account - use the alternative Step 1? instead.
Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file /etc/httpd/httpd.conf with only ExecCGI option.
The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
NOTE: The ScriptAliasmust come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
Example httpd.conf entries:
ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
Alias /twiki/ "/home/httpd/twiki/"
<Directory "/home/httpd/twiki/bin">
Options +ExecCGI
SetHandler cgi-script
AllowOverride all
Allow from all
</Directory>
<Directory "/home/httpd/twiki/pub">
Options FollowSymLinks +Includes
AllowOverride None
Allow from all
</Directory>
Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.
Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
IMPORTANT: On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary.
Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
NOTE: This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
replace user twiki with your own username
Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
NOTE: The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using sed: for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Step 3: Set the Main Configuration File
Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
Set the file extension in the $scriptSuffix variable to cgi or pl if required.
Make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to mach the location of your RCS binaries.
Security issue: Directories twiki/data , twiki/templates and all its subdirectories should be set so that they are not visible as a URL. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.
Step 4: Finish Up from Your Browser
Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
Edit the TWikiPreferences topic in the TWiki:TWiki web to set the WIKIWEBMASTER email address, and other preferences.
Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
Enable email notification of topic changes, TWikiSiteTools has more.
Edit the WebNotify topic in all webs and add the users you want to notify.
That's it for the standard virgin installation of TWiki. Read on for server-level customization options.
Additional Server-Level Options
With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.
Enabling Authentication of Users
If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly: Redirect /urlpath/to/TWiki/index.html http://your.domain.com/urlpath/to/TWiki/bin/view AuthUserFile /filepath/to/TWiki/data/.htpasswd ErrorDocument 401 /urlpath/to/TWiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
NOTE: In case you renamed the CGI script files to have a file extension you need to reflect that in the edit, view, preview, etc entries in .htaccess.
NOTE: The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect you need to enable it: Add "AllowOverride All" to the Directory section of access.conf for your twiki/bin directory.
Copy the TWikiRegistrationPub topic to TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
HINT: You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are processed correctly.
NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
Create a new topic to check if authentication works.
Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
Edit the WebPreferences topic in each web, if necessary: set access priviliges.
Adding a New Web
To create a new web:
Create a new web data directory under twiki/data and check the file permission of the directory.
Use a name starting with characters A..Z, followed by a..z and/or 0..9 characters, but not a WikiWord.
Copy all files from the twiki/data/_default directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use cp -p). The data files must be writable by the owner the CGI scripts are running on (usually, nobody).
HINT: You can set permissions of .txt and .txt,v files to -rw-rw-rw- (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
Add the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, TWikiPreferences:
Add the new web to the %WIKIWEBLIST% variable.
Update the web settings by editing the WebPreferences topic of the new web:
Customize the %WEBTOPICLIST% variable to contain the web-specific links you prefer.
Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
Set Plugins, access privileges, custom variables, other web-level options (ex: %WEBCOPYRIGHT% can be set for an individual web).
Add the new web to the color-coded web directory table by editing the TWikiWebsTable topic.
Test the new web: view pages, create a new page.
That's it for a basic new web set-up!
Optionally, you can also:
Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.
NOTE: User home topics are located in the netfrag.org.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to netfrag.org.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!
Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs
Overview
TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
Meta Data Syntax
Format is the same as in TWikiVariables, except all fields have a key.
%META:<type>{key1="value1" key2="value2" ...}%
Order of fields within the meta variables is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the variables themselves is defined).
Each meta variable is on one line.
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Meta Data Specifications
The current version of Meta Data is 1.0, with support for the following variables.
Format of this topic, will be used for automatic format conversion
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed.
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
form fields remain in the order they are defined
the diff function output appears in a logical order
The recommended sequence is:
META:TOPICINFO
text of topic
META:TOPICMOVED (optional)
META:TOPICPARENT (optional)
META:FILEATTACHMENT (0 or more entries)
META:FORM (optional)
META:FIELD (0 or more entries; FORM required)
Viewing Meta Data in Page Source
When viewing a topic the Raw Text link can be clicked to show the text of a topic (ie: as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic
Rendering Meta Data
Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.
Current support covers:
Prefix for parents, only if there are parents; default ""
suffix="..."
Suffix, only appears if there are parents; default ""
separator="..."
Separator between parents, default is " > "
Known Issues
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.
-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001
independently determine who can see, edit, rename, move or delete topics
set permissions by individual users and user groups
revision control automatically saves topic changes:
uses the established standard RCS (Revision Control System)
efficiently stores every change made to the original version
allows comparison of changes between any two versions, and review of any version, as formatted or raw text
referred-by searches that list all topics in a web or site wide that link to a particular page
hierarchical parent-child topic navigation:
automatically links a new page as the "child" of the page it was created from
allows manual assignment of parent page from a list of all topics in the local web
offers navigation displays, by topic parent, or by related topic
The configuration of your TWiki site and your own user account determine which of these features you can use.
How to create and edit a page
Adding and editing information on existing pages, and creating new pages, is TWiki's main function.
To modify a topic, click the [Edit] link at the bottom left of every page. An editing window appears. Type away. Use the GoodStyle and TextFormattingRules links to get pop-up window help.
Click [Preview Changes] to see how your edit looks.
Click [Save Changes] to save.
To add a new page, the simplest way is to type a new WikiName on an existing page. When the page is saved, the new name will appear highlighted, with a ? at the end: click the ? and a new edit window appears. Enter, preview and save as usual. The new page now exists.
How to attach files and use other features
The color-coded control strip at the bottom of every page displays a series of links, including [Attach] (for attachments), [Ref-by] (to display referring pages), and [More], which opens a new screen of additional controls).
Most controls are self-explanatory, and also include explanatory text and help links.
Experiment. You can always cancel or go Back whenever you like.
Get in-depth info from the complete documentation?, including the User's Guide and Reference Manual.
How to rename, move or delete a page
You can now rename, move and delete individual topics from your browser. All three options are available by clicking More on the control strip at the bottom of every page. The access settings for a topic, web or entire site may be disabled for one or more of the three options. In any case, all three are similar and extremely self-explanatory.
On the topic you want to change, click More > Rename/move
To move or delete: select the target web (Trash for delete)from the pull-down menu; otherwise, leave on the current web
To rename: fill in a new WikiName (otherwise, leave the current topic name)
To update occurrences of the topic name on other pages: From the list of pages that link to the topic, check or uncheck each entry as you desire - only checked links will be updated;
Click Rename/move: the topic will be renamed and links to the topic updated.
Any problems are listed ; you can change them later.
If a referring page can't be update because it's locked (ex: someone's editing), it appears on an alert. You can missed pages later by again pressing Rename/move.
Deleting means moving the topic to the Trash web. Since all webs share the one Trash, name conflicts may come up.
NOTE: Keep in mind that moving a topic from a view-restricted web to a public web or the Trash web will compromise security.
See: ManagingTopics for more details.
Last updated: MikeMannix? - 30 Oct 2001
Plug-in enhanced feature add-ons, with a Plugin API for developers
Overview
You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:
add virtually unlimited features while keeping the main TWiki code compact and efficient;
heavily customize an installation and still do clean updates to new versions of TWiki;
rapidly develop new TWiki functions in Perl using the Plugin API.
Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.
Preinstalled Plugins
TWiki comes with three Plugins as part of the standard installation.
DefaultPlugin optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules? for simple custom processing.)
EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.
InterwikiPlugin is preinstalled but can be disabled or removed. Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own.
Installing Plugins
Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.
Most Plugins can be installed in three easy steps, with no programming skills required:
Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
Check the demo example on the Plugin topic: if it's working, the installation was fine!
Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.
Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.
Doc page: Read all available info about the Plugin; download the attached distribution files.
Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.
On-Site Pretesting
To test new Plugins on your installation before making them public, you may want to use one of these two approaches:
Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
Test Plugins and other new features in the Test installation until you're satisfied.
If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.
Method 2: List the Plugin under Test in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Test web and do the testing there.
Managing Plugins
When you finish installing a Plugin?, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.
Setting Preferences
Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
All Plugin modules present in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the netfrag.org web for the Plugin topics. Settings in TWikiPreferences are:
Set INSTALLEDPLUGINS = DefaultPlugin, ...
Set DISABLEDPLUGINS = EmptyPlugin, ...
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
Set SHORTDESCRIPTION = Blah blah woof woof.
Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
Set DEBUG = 0
The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
Listing Active Plugins
Plugin status variables let you list all active Plugins wherever needed. There are two list formats:
The %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
HeadlinesPlugin: Build news portals that show headline news based on RSS news feeds from news sites.
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
TablePlugin: Control attributes of tables and sorting of table columns
VisualConfirmPlugin: Plugin for visual confirmation of new user registration.
The TWiki Plugin API
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
Available Core Functions
The lib/TWiki/Func.pm implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
If you use functions not in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.
Predefined Hooks
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.
Plugin Version Detection
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
All modules require a $VERSION='0.000' variable, beginning at 1.000.
The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).
With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API? Plugins by providing a programming interface for TWiki.
The DefaultPlugin Alternative
DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.
Anatomy of a Plugin
A basic TWiki Plugin consists of two elements:
a Perl module, ex: MyFirstPlugin.pm
a documentation topic, ex: MyFirstPlugin.txt
The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call.
In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API?, you're ready to develop Plugins.
Creating the Perl Module
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. EmptyPlugin.pm contains no executable code, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API? specs for more information.
Writing the Documentation Topic
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package?.) To create a documentation topic:
Copy the Plugin topic template from EmptyPlugin. To copy the text, go to the page and:
click Edit
select all in the Edit box & copy
Cancel the edit
paste & save as a text file or new topic on your site
Customize the template for your Plugin; you'll probably want to post a working version on your local TWiki site.
Save your topic as a text file, for use in packaging? and publishing? your Plugin.
OUTLINE: Doc Topic Contents
Check EmptyPlugin on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:
Syntax Rules: <Describe any special text formatting that will be rendered.>"
MyFirstPlugin Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
Plugins Preferences <If user settings are needed, explain... Entering valuse works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
Set <EXAMPLE = value added>
How-to Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"
Test Example: <Include an example of the Plugin in action: if it works, the installation was a success!>"
Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Packaging for Distribution
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
Publishing for Public Use
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
Post the Plugin documentation topic in the TWiki:Plugins web:
create a new topic using the Plugin name, ex: MyFirstPlugin.txt
paste in the topic text from Creating Plugin Documentation? and save
Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
netfrag.org Site-Level Preferences
The following settings are site-level preferences , e.g. affecting all users in all netfrag.org webs. These preferences can be overwritten by web preferences (topic WebPreferences in each netfrag.org web) and user preferences (your personal topic, i.e. TWikiGuest? in the netfrag.org.Main web)
Preferences:
Note: To automatically list all non-hidden webs in alphabetical order you can use this variable instead: Set WIKIWEBLIST = MainOriginal?PadPlugins?TWiki?
List of topics of a web: (the second line of a topic, is overwritten by web preferences)
Set PREVIEWBGIMAGE = /twiki/pub/TWiki/PreviewBackground/previewbg.gif
Background color of non existing topic: ( default cornsilk or #FFFFCE )
Set NEWTOPICBGCOLOR = #FFFFCE
Font color of non existing topic: ( default #0000FF )
Set NEWTOPICFONTCOLOR = #00ffff
Horizontal size of text edit box: (can be overwritten by user preferences)
Set EDITBOXWIDTH = 100
Vertical size of text edit box: (can be overwritten by user preferences)
Set EDITBOXHEIGHT = 30
Default state of the Release edit lock (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time: (can be overwritten by user preferences)
Set RELEASEEDITLOCKCHECKBOX = checked
Default state of the Minor Changes, Don't Notify (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty: (can be overwritten by user preferences)
Set DONTNOTIFYCHECKBOX = checked
Default state of the link check box in the attach file page. Checkbox is initially checked if Set ATTACHLINKBOX = checked="checked", or unchecked if empty (Set ATTACHLINKBOX =). If checked, a link is created to the attached file at the end of the topic: (can be overwritten by user preferences)
Set ATTACHLINKBOX =
Format of file link when the link check box is checked: (can be overwritten by user preferences)
Note: Keyword $name gets expanded to filename; $comment to comment; \t to tab (3 spaces for bullets).
Format of images when the link check box is checked: (can be overwritten by user preferences)
Set ATTACHEDIMAGEFORMAT = \t* $comment:
Note: Above image is shown as broken, it gets expanded correctly when you attach an image.
Note: Keyword $name gets expanded to filename; $comment to comment; $size to width="..." height="..." attribute of img tag; \t to tab (3 spaces for bullets).
Mail host for outgoing mail. This is used for WebChangesAlert if Perl module Net::SMTP is installed. If not, or if SMTPMAILHOST is empty, the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg). Examples: mail.your.company or localhost
Set SMTPMAILHOST = localhost
Mail domain sending mail. SMTP requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you. Examples: twiki.your.company
Set SMTPSENDERHOST = localhost
TWikiPlugins configuration: All plugin modules that exist in the lib/TWiki/Plugins directory are activated automatically unless disabled by DISABLEDPLUGINS. You can optionally list the installed plugins in INSTALLEDPLUGINS. This is useful to define the sequence of plugin execution, or to specify other webs then the TWiki web for the plugin topics. Specify plugins as a comma separated list of topics.
Note: In case you have a rough plugin you can disable all plugins with the $disableAllPlugins flag in the TWiki.cfg file.
http-equiv meta tags for view, rdiff, attach, search* scripts:
* Set HTTP_EQUIV_ON_VIEW =
http-equiv meta tags for edit script. Example to expire immediately: Set HTTP_EQUIV_ON_EDIT = <meta http-equiv="Expires" content="%GMTIME{"$day $month, $year - $hour:$min:$sec"}% GMT">
* Set HTTP_EQUIV_ON_EDIT =
http-equiv meta tags for preview script:
* Set HTTP_EQUIV_ON_PREVIEW =
Users or groups allowed to change or rename this TWikiPreferences topic: (I.e. TWikiAdminGroup)
Set ALLOWTOPICCHANGE =
Set ALLOWTOPICRENAME =
Site-level preferences that are not allowed to be overridden by WebPreferences and user preferences:
Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKIWEBMASTER, SMTPMAILHOST , SMTPSENDERHOST
Notes:
A preference is defined as: 6 spaces * Set NAME = value Example:
Set WEBBGCOLOR = #FFFFC0
Preferences are used as TWikiVariables by enclosing the name in percent signs. Example:
When you write variable %WEBBGCOLOR% , it gets expanded to #000000 .
The sequential order of the preference settings is significant. Define preferences that use other preferences first, i.e. set WEBCOPYRIGHT before WIKIWEBMASTER since %WEBCOPYRIGHT% uses the %WIKIWEBMASTER% variable.
You can introduce new variables and use them in your topics and templates. There is no need to change the netfrag.org engine (Perl scripts).
Related Topics:
WebPreferences has preferences of the netfrag.org.TWiki web.
TWikiUsers has a list of user topics. User topics can have optional user preferences.
To edit pages on this netfrag.org Collaborative Web, you must have a registered user name and password. Note: You can also login anonymously as user TWikiGuest with password guest
To register as a new user, simply fill out this form:
Submitting the form will automatically:
Create an account for you, so that you can start editing pages using your WikiName.
Create your personal netfrag.org topic using your WikiName as topic name, and add the data you submitted to the topic.
Add your name to the list of users in the TWikiUsers topic in the netfrag.org.Main web.
Send you a confirmation of your registration by email.
Once registered you can login using your WikiName and password.
If you have any questions about registration, send an email to webmaster@netfrag.org.
To edit pages on this netfrag.org Collaborative Web, you must have a registered user name and password. Note: You can also login anonymously as user TWikiGuest with password guest
To register as a new user, simply fill out this form:
Submitting the form will automatically:
Create an account for you, so that you can start editing pages using your WikiName.
Create your personal netfrag.org topic using your WikiName as topic name, and add the data you submitted to the topic.
Add your name to the list of users in the TWikiUsers topic in the netfrag.org.Main web.
Send you a confirmation of your registration by email.
Once registered you can login using your WikiName and password.
If you have any questions about registration, send an email to webmaster@netfrag.org.
Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWikiShorthand gives you all the power of HTML with a simple coding system that takes little time to learn. It's all layed out below - refer back to this table in a pop-up window from the Edit screen.
Formatting Command:
Example: You write:
You get:
Paragraphs:
Blank lines will create new paragraphs.
1st paragraph
2nd paragraph
1st paragraph
2nd paragraph
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables.
---++ Sushi
---+++ Maguro
Sushi
Maguro
Bold Text:
Words get bold by enclosing them in * asterisks.
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores.
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
=Fixed font=
Fixed font
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
==Bold fixed==
Bold fixed
Note: Make sure to "stick" the * _ = == signs to the words, e.g. take away spaces.
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want HTML code to be interpreted. Note: Each tag must be on a line by itself.
Separator:
At least three dashes at the beginning of a line.
-------
List Item:
Three spaces and an asterisk.
* bullet item
bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
* nested stuff
nested stuff
Ordered List:
Three spaces and a number.
1 Sushi
1 Dim Sum
Sushi
Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition. Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the non-breaking-space entity.
Sushi: Japan
Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars. Note:| *bold* | cells are rendered as table headers. Note:| spaced | cells are rendered center aligned. Note:| spaced | cells are rendered right aligned. Note:| 2 colspan || cells are rendered as multi-span columns. Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different netfrag.org web write Webname.TopicName.
Forced Links:
You can create a forced internal link by enclosing words in double square brackets. Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
Anchors:
You can define a link reference inside a netfrag.org topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
[[WebHome#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS
Using HTML
You can use just about any HTML tag without a problem, HOWEVER, it's recommended NOT to. Using TWikiShorthand, you can do practically anything you'd normally do with HTML, and it keeps the text uncluttered and easy for people to browse edit.
Hyperlinks
Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
Internal Links
GoodStyle is a WikiWord that links to the GoodStyle topic located in the current netfrag.org web.
NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
External Links
http://..., https://..., ftp://... and mailto:...@... are linked automatically.
Email addresses like name@domain.com are linked automatically.
[[Square bracket rules]] let you easily create non-WikiWord links?.
TWiki Variables
TWikiVariables are names that are enclosed in percent signs % that are expanded on the fly. Using the existing variables, and even creating your own, adds an amazing extra level of content to your posts. For example:
%TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
%WEB% : The current web, is TWiki.
%TOPIC% : The current topic name, is TWikiShorthand.
%ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif to show the URL of the file or the image in your text.
%INCLUDE{"SomeTopic"}% : Server side include, includes another topic. The current netfrag.org web is the default web. Example: %INCLUDE{"TWiki.TWikiWebsTable"}%
TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ:
Q: Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
A: The '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<' instead of '<', and '>' instead of '>'. Example: Type 'prog <filename>' to get 'prog <filename>'.
Q: Why is the '&' character sometimes not displayed?
TWiki provides an intuitive way to meet and collaborate, that aspires to the Zen ideals known as WabiSabi. It finds beauty in the imperfect and ephemeral and constantly evolving. When it comes down to it, that's all you need.
Wiki wiki means "quick" in Hawaiian. The shuttle at Honolulu Airport is called the wiki wiki bus, which is where the original Wiki web got its name.
TWiki is short for TakeFive Wiki from the name of the company where its founder worked. (It was later discovered that Twiki is also the name of an AI robot that co-starred in the Buck Rogers... movie and TV show from 1979 - its head is in the logo.)
Selected TWiki Topics...
TWikiPages tells you how to do administrative things, like renaming topics.
WikiCulture looks at the unique type of collaboration Wiki systems offer.
WikiReferences links to articles and books about collaboration and Wiki technology.
NOTE: If you have to log-in to us TWiki, for example, if Twiki is running on an intranet, it automatically signs new pages with your WikiName. If your TWiki installation doesn't require a log-in, TWiki gives everyone the same username: TWikiGuest?.
TWikiTM is a trademark of PeterThoeny, originator and lead developer.
TWiki is developed as Free Software under the GNU/GPL
Utilities for searching, navigation, and monitoring site activity
Overview
TWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to email alerts when topics are edited, and WebStats, to generate detailed activity reports.
WebNotify Recent Changes Alert
Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a deamon in regular intervals. The script sends an automated email to subscribed users if topics were changed in a web within last interval.
netfrag.org will use the Net::SMTP module if it is installed on your system. Set this with the SMTPMAILHOST variable in TWikiPreferences.
You can use an external mail program, like sendmail, if the Net::SMTP module is not installed. Set the program path in $mailProgram in TWiki.cfg.
Net::SMTP can be easily disabled (ex: if there is an installation error) by setting SMTPMAILHOST in TWikiPreferences to an empty value.
You can set a separate SMTPSENDERHOST variable to define the mail sender host (some SMTP installations require this).
Setting the Automatic Email Schedule
For Unix platforms: Edit the cron table so that mailnotify is called in an interval of your choice. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:
The above line will call mailnotify at 15 minutes and 45 minutes past every hour. The -q switch suppresses all normal output.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows NT/2000: You can use a scheduled task if you have administrative privileges.
Note: AT on an NT machine is pretty limited.
Microsoft lists several third-party
replacements
(as of 2001-11-20, none of them free).
WebStatistics Site Usage Log
You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.
You can automatically generate usage statistics for all webs. To enable this:
Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in TWiki.cfg are set. This will generate log entries in file twiki/data/log<date>.txt .
The WebStatistics topic must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry: 0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example: 0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
Generating Statistics Manually by URL
The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
Update current month for all webs: http://mydomain.com/twiki/bin/statistics
Update current month for Main web only: http://mydomain.com/twiki/bin/statistics/Main
Update January 2000 for Main web: http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
WebSearch
WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:
topic title or full-text search
regular expressions
search within web or site-wide
index-style A-Z alphabetical listing sorted topic title
many more
See also: TWikiVariables for including hard-coded searches in text.
WebChanges
To check for the most recently edited topics while on-site, use the WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.
This is simply a preset SEARCH. The number of topics listed by the limit parameter.:
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
Overview
Skins are customized TWikiTemplates files. You can use skins to change the look of a netfrag.org topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.
Defining Skins
Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.
Definition of the templates used to render all HTML pages displayed in TWiki
Overview
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML mark-up for template-specific content. Templates are used to define page layout?, and also to supplydefault content? for new pages.
Major changes from the previous template system
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
separates a set of common template parts into a base template that is included by all of the related templates;
defines common variables, like a standard separator (ex: "|"), in the base template;
defines variable text in the individual templates and passes it back to the base template.
Functional Specifications
Special template directives (or preprocessor commands) are embedded in normal templates.
Use of template directives is optional, templates work without them.
All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
Directives:
%TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
%TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
%TMPL:END%: Ends variable definition.
%TMPL:P{"var"}%: Prints a previously defined variable.
Variables are live in a global name space, there is no parameter passing.
Two-pass processing, so that you can use a variable before declaring it or after.
Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads just the twiki.tmpl, like twiki.print.tmpl, that redefines the header and footer.
NOTE: The template directives work only for templates, they do not get processed in topic text.
TWiki Master Template
All common parts are defined in a master template, twiki.tmpl, that all other templates use.
Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%
Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}%
Skeleton of oops dialog
Types of Template
There are two types of templates:
HTML Page Templates: Defines layout of netfrag.org pages
Template Topics: Defines default text when you create a new topic
HTML Page Templates
netfrag.org uses HTML template files for all actions like topic view, edit, preview and so on. This allows you to change the look and feel of all pages by editing just some template files.
The template files are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded per web. The following search order applies:
twiki/templates/$webName/$scriptName.tmpl
twiki/templates/$scriptName.tmpl
Note:$webName is the name of the web (ex: Main), and $scriptName is the script (ex: view).
Note:TWikiSkins can be defined to overload the standard templates.
Special variables are used in templates, especially in view, to display meta data.
Template Topics
Template topics define the default text for new topics. There are three types of template topics:
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. The following search order applies when you create a new topic:
The topic name specified by the templatetopic CGI parameter.
WebTopicEditTemplate in the current web.
WebTopicEditTemplate in the TWiki web.
Template Topics in Action
Here is an example for creating new topics based on a specific template topic:
Above form asks for a topic name. A hidden input tag of name "templatetopic" specifies the ExampleTopicTemplate as the template topic. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%WEB%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="submit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
The "onlywikiname" parameter enforces WikiWords for topic names.
Note: Use can use the %WIKIUSERNAME% and %DATE% variables in your topic templates as the signature; those variables are expanded when a new topic is created. The standard topic signature is: -- %WIKIUSERNAME% - %DATE%
Templates by Example
Attached is an example of an oops base template oopsbase.tmpl and a example oops dialog oopstest.tmpl which is based on the base template. NOTE: This isn't the release version, just a quick, simple demo.
Base template oopsbase.tmpl
The first line declares the delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%
Each oops template basically just defines some variables and includes the base template that does the layout work.
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
* Some more blah blah blah blah blah blah blah blah blah blah...
* Param1: %PARAM1%
* Param2: %PARAM2%
* Param3: %PARAM3%
* Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%
Sample screen shot of oopstest.tmpl
With URL: .../bin/oops/Test/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
Known Issues
A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template is a structurally complete HTML document with a .tmpl filename extension - it contains unresolved %VARIABLES%, but can still be previewed directly in a browser.
This step-by-step, hands-on tutorial gets you up to speed with all the TWikiSite basics, in mere minutes...
1. Get set...
Open two browser windows, so that you can follow these steps in one window, while trying things out in the other.
2. Take a quick tour...
A TWikiSite is divided into webs; each one usually represents one area of collaboration. You can navigate the webs from the upper right corner of each web page.
Each web has hyperlinked topics, displayed as pages in your browser.
The home page in each web is the Home topic.
To browse a TWiki web, just click on any highlighted link. These links are called WikiWords and comprise two or more words with initial capitals, run together.
If you know the name of a topic, you can jump directly to it by typing its name into the Go field on the top of the page. Type WebSearch to jump to the search page. Hint: Do not confuse the Go field with search.
You can search each TWiki web. Enter a search string in the Home topic or the WebSearch topic accessible from the Search link on each topic. TWiki searches for an exact match; optionally, you can also use RegularExpressions.
3. Open a private account...
To edit topics, you need to have a TWiki account.
Go to the TWikiRegistration page to create your TWiki account. Fill in a couple of lines and you're set!
4. Check out TWiki users, groups, offices...
Go to the TWikiUsers topic in the TWiki.Main web; it has a list of all users of TWiki. Your WikiName will be in this list after you register.
Go to the TWikiGroups? topic in the TWiki.Main web; it has a list of groups which can be used to define fine grained TWikiAccessControl in TWiki.
Go to the OfficeLocations? topic in the TWiki.Main web; it has a sample list of corporate offices. This type of set-up can be used for departments, client companies, or any other type of organizational divisions.
5. Test the page controls...
Go to the bottom of the page? to see what you can do. The color-coded control strip has a collection of action links:
[[Edit] - add to or edit the topic (discussed later)
[Attach] - attach files to a topic (discussed later)
[Ref-By] - find out what other topics link to this topic (reverse link)
[Printable] - goes to a stripped down version of the page, good for printing
[Diffs] - topics are under revision control - [Diffs] shows you the complete change history of the topic, ex: who changed what and when.
[r1.3 | > | r1.2 | > | r1.1] - view a previous version of the topic or the difference between two versions.
[More] - additional controls, like [Rename/move], version control and setting the topic's parent.
6. Change a page, and create a new one...
Go to the Test?. This is the sandbox web, where you can make changes and try it all out at will.
Click the [Edit] link. You are now in edit mode and you can see the source of the page. (Go to a different topic like TestTopic3? in case you see a "Topic is locked by an other user" warning.)
Look at the text in edit mode and compare it with the rendered page (move back and forth in your browser.)
Notice how WikiWords are linked automatically; there is no link if you look at the text in edit mode.
Now, create a new topic - your own test page:
In edit mode, enter a new text with a WikiWord, ex: This is YourOwnSandBox topic.
Preview and save the topic. The name appears, highlighted, with a linked question mark at the end. This means that the topic doesn't exist yet.
Click on the question mark. Now you're in edit mode of the new topic.
Type some text, basically, like you write an email.
A signature with your name is already entered by default. NOTE: The Main. in front of your name means that you have a link from the current web to your personal topic located in the Main web.
Preview and save the topic...
Learn about text formatting. You can enter text in TWikiShorthand, a very simple markup language. Follow the TWikiShorthand link to see how, then:
Go back to your sandbox topic end edit it.
Enter some text in TWikiShorthand: bold text, italic text, bold italic text, a bullet list, tables, paragraphs, etc. Hint: If you need help, click on the TextFormattingRules link located below the text box in edit mode.
Preview and save the topic.
7. Use your browser to upload files as page attachments...
You can attach any type of file to a topic - documents, images, programs, whatever - where they can be opened, viewed, or downloaded.
Attaching files is just like including a file with an email.
Go back to your sandbox topic and click on the [Attach] link at the bottom.
Click [Browse] to find a file on your PC that you'd like to attach; enter an optional comment; leave everything else unchecked.
Click [Upload file], then scroll to the end of the page to see the new attachment listing.
Do this again - this time, upload a GIF, JPG or PNG image file.
Check the [Link:] box to Create a link to the attached file at the end of the topic. The image will show up at the bottom of the topic.
To move the image, edit the topic and place the last line (containing %ATTACHURL%) anywhere on the page.
If you have a GIF, JPG or PNG image of yourself, your cat, your sprawling family estate...why not upload it now to personalize your account page: Main.guest?
8. Get email alerts whenever pages are changed...
WebNotify is a subscription service that automatically notifies you by email when topics change in a TWiki web. This is a convenience service - for many people, checking email is easier than checking the Web.
If you're using TWiki to collaborate on a project, it's important to know when anyone on your team posts an update. If you're following a specific discussion, it's convenient to know when there's new input.
Alerts are emailed as links to individual topics that've been changed in a set period: each day, every hour, whatever is configured for your system.
It's strongly recommended that you try out the service by subscribing to each TWiki web that's relevant to you. You can subscribe and unsubscribe instantly, on a per web basis using WebNotify.
That's it! You're now equipped with all the TWiki essentials. You are ready to roll.
NOTE: When first using TWiki, it will probably seem strange to be able to change other people's postings - we're used to separating individual messages, with email, message boards, non-Wiki collaboration platforms. Don't worry about it. You can't accidentally delete important stuff - you can always check previous versions, and copy-and-paste from them if you want to undo any changes. After a short while, TWiki-style free-form communication becomes second-nature. You'll expect it everywhere!
-- MikeMannix? - 01 Dec 2001
Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release)
Overview
This guide describes how to upgrade either from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001.
The latest version of TWiki (01-Dec-2001) is a small incremental release over the 01-Sep-2001 version.
The 01-Sep-2001 version involves several major new features and numerous enhancements to the last full version (01-Dec-2000). The file system set-up is almost identical, but much of the underlying data structure and processes is new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.
Upgrade Requirements
To upgrade from a 01-Dec-2000 or 01-Sep-2001 standard installation to the latest 01-Dec-2001 TWiki Production Release, follow the instructions below.
To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.
Major Changes from TWiki 01-Sep-2001
The latest 01-Dec-2001 release includes the following new features and enhancements compared to the 01-Sep-2001 release:
FormattedSearch - New format="" parameter in %SEARCH{}% variable for database like reporting.
Various bug fixes
Major Changes from TWiki 01-Dec-2000
The 01-Sep-2001 release includes the following new features and enhancements compared to the 01-Dec-2000 release:
TWikiPlugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
InterwikiPlugin (preinstalled) - Link to external sites with text aliases, SiteAlias:Page; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.)
SuperAdministrator Group - Lets you to make the members of one user group - by default, TWikiAdminGroup - into TWiki superusers, with the ability to overwrite locked topics from the browser interface. (This gets around the problem of topic lockouts, caused by typos in access privilege definitions.)
HierarchicalNavigation uses new Meta Data variables to link hierarchically.
Convert to XHTML - Pages are rendered for display in XHTML 1.0, as far as possible without breaking HTML 3.2 compliance.
TWiki Directory Structure and File Names
The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:
A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.
Standard Upgrade Procedure from 01-Sep-2001 to 01-Dec-2001 Release
This incremental update can be performed easily.
The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Sep-2001 release.
Back up and prepare:
Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.
Create a temporary directory and unpack the ZIP file there.
Update files in TWiki root:
Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
Update template files:
Overwrite all template files in $TWIKIROOT/templates with the new ones.
Update script files:
Overwrite all script files in $TWIKIROOT/bin with the new ones.
Update library files:
Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
Overwrite all *.pm library files in $TWIKIROOT/lib/TWiki and $TWIKIROOT/lib/TWiki/Plugins with the new ones.
Update data/TWiki files: (in case you want the updated docs)
Using your browser, merge the new TWiki.TWikiRegistration topic (or TWiki.TWikiRegistrationPub in case you used that one) into your existing TWiki.TWikiRegistration topic.
In the temporary twiki/data/TWiki directory where you unzipped the installation package:
Remove the files you do not want to upgrade: TWikiPreferences.*, TWikiWebsTable.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory.
Update pub/TWiki files:
Move the new pub/TWiki/TWikiDocGraphics directory into your $TWIKIROOT/pub/TWiki directory.
Standard Upgrade Procedure from 01-Dec-2000 to 01-Dec-2001 Release
The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.
Before Switch:
After Switch:
Current 01-Dec-2000:
New 01-Dec-2001:
Obsolete 01-Dec-2000:
New 01-Dec-2001:
twiki/templates/
twiki/templates2/
twiki/templates1/
twiki/templates/
twiki/bin/
twiki/bin/2/
(overwritten)
twiki/bin/
(N/A)
twiki/bin/lib/
(N/A)
twiki/lib/
twiki/data/TWiki
twiki/data/TWiki2
twiki/data/TWiki1
twiki/data/TWiki
(other directories do not change)
Alternatively you could move the existing installation away, install the 01-Dec-2001 release into it's place and move your webs and pub files back.
Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Dec-2001 release, importing your original page data and related files:
Pre-Upgrade Preparation
Two major areas of TWiki functionality - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.
The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/
Step 1: Backup & Unpack
Back up all existing TWiki directories twiki/bin, twiki/pub, twiki/data, twiki/templates.
Create a temporary directory and unpack the ZIP file there:
mkdir -p ~/tmp/ cp -p ~/downloads/TWiki20011201.zip ~/tmp/ cd ~/tmp/ unzip ~/tmp/TWiki20011201.zip
Step 2: Upgrade TWiki document files
Move the document files to your TWiki root ( twiki ):
mv ~/tmp/TWiki*.html $TWIKIROOT mv ~/tmp/index.html $TWIKIROOT mv ~/tmp/readme.txt $TWIKIROOT mv ~/tmp/license.txt $TWIKIROOT
Step 3: Install new template files
Move & rename the template directory to a temporary twiki/templates2 directory, ex:
mv ~/tmp/templates $TWIKIROOT/templates2
Pay attention to the file and directory permissions (security issue). Set file permissions, ex:
chmod 644 *.cgi
Step 4: Install new data and pub files
Move the TWiki web to a temporary TWiki2 twiki/data/TWiki2 directory. Do the same to files attached to this web, ex:
mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2 mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2
Move & rename the Know web to a temporary twiki/data/Know2 directory, ex:
mv ~/tmp/data/Know $TWIKIROOT/data/Know2 mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2
Move the _default and Trash web, ex:
mv ~/tmp/data/_default $TWIKIROOT/data mv ~/tmp/data/Trash $TWIKIROOT/data
Move the MIME types file, ex:
mv ~/tmp/data/mime.types $TWIKIROOT/data
Move the TWiki logo files, ex:
mv ~/tmp/pub/*.gif $TWIKIROOT/pub
Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).
In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed the user of your cgi-scripts, i.e. www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Step 5: Install new CGI scripts
Move & rename the CGI script directory to a temporary twiki/bin/2 directory, ex:
mv ~/tmp/bin $TWIKIROOT/bin/2
If necessary, change the script names to include the required extension, ex: .cgi
Copy any additional scripts you might have from the 01-Dec-2000 release, ex:
cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2
In case you use basic authentication, rename .htaccess.txt to .htaccess and customize it, ex:
cd $TWIKIROOT/bin/2 mv .htaccess.txt .htaccess diff ../.htaccess . and merge the content
Pay attention to the file and directory permissions (security issue). Set permissions, ex:
chmod 755 *.cgi
Step 6: Install new Perl library files
Move the lib directory to a temporary twiki/bin/lib directory, ex:
mv ~/tmp/lib $TWIKIROOT/bin
Pay attention to the file and directory permissions (security issue). Set permissions, ex:
chmod 644 *.pm
Step 7: Set configurations and test installation
Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
cd $TWIKIROOT/bin/lib diff ../wikicfg.pm TWiki.cfg
Make sure to set the correct temporary location of templates and scripts, ex:
$scriptUrlPath = "/twiki/bin/2"; $templateDir = "/home/httpd/twiki/templates2";
Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm
Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:
Old URL: http://localhost/cgi-bin/view
New URL: http://localhost/cgi-bin/2/view
Step 8: Update topics
You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Dec-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.
Remember that you now have two TWiki webs:
The original TWiki web.
The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.
In case you customized TWiki.TWikiRegistration, merge your changes back into TWiki2.TWikiRegistration.
Copy TWiki.TWikiWebsTable to TWiki2.TWikiWebsTable.
Do the same for any other topics you might have created in the TWiki web.
In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.
Add your webs to WIKIWEBLIST
Set the WIKIWEBMASTER
Set the SMTPMAILHOST
In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)
Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
* Set NOSEARCHALL = on
In WEBTOPICLIST, remove the %WEB% . {} decoration from the list (it is now in the templates), ex:
* Set WEBTOPICLIST = <a href="Home">Home</a> | <a href="WebChanges">Changes</a> | <a href="WebIndex">Index</a> | <a href="WebSearch">Search</a> | Go <input type="text" name="topic" size="16" />
Add a these new preferences:
* Set DENYWEBVIEW = * Set ALLOWWEBVIEW = * Set DENYWEBRENAME = * Set ALLOWWEBRENAME =
Set the FINALPREFERENCES:
* Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
Optional: In WebSearch of all webs, replace content with this one line:
%INCLUDE{"%TWIKIWEB%.WebSearch"}%
Optional: In WebChanges of all webs, replace content with this one line:
%INCLUDE{"%TWIKIWEB%.WebChanges"}%
Step 9: Customize template files
NOTE: Skip this step if you did not customize your template files.
Remember that you have now two template directories:
The original twiki/templates.
The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.
Customized templates and skins need to be upgraded to the new TWikiTemplates. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.
Create a replacement WebForm topic based on twikicatitems.tmpl in each web that uses a Category Table. See details in TWikiForms and compare with the settings in the Know2.WebPreferences topic.
NOTE: Do not remove the twikicatitems.tmpl file, it is still used for topics that are of the old format.
Searches need to be adjusted to deal with format change. It is possible to define a regular expression search that can deal at the same time with topics in the old format and new format.
Example: List all topics in the Know web that have a TopicClassification? of PublicFAQ?: %SEARCH{ "[T]opicClassification.*?(td..td|value\=).*?[P]ublicFAQ" casesensitive="on" regex="on" nosearch="on" web="Know"}% (The [T] and [P] is done so that search does not find the topic where this search string is located in!)
Example: Create a link that lists all topics in the Know web with a TopicClassification? of PublicFAQ?: [[%SCRIPTURL%/search%SCRIPTSUFFIX%/Know/?scope=text &search=%5BT%5DopicClassification.*%3F%28td..td%7C value%5C%3D%29.*%3F%5BP%5DublicFAQ®ex=on][All Public FAQ]] All Public FAQ
For each web that has a custom notedited.tmpl template, create an equivalent WebTopicEditTemplate to conform with the new TemplateTopics. The new format replaces the notedited.tmpl, notext.tmpl and notwiki.tmpl templates.
Step 10: Switch over to new installation
In this step, you move the working 01-Dec-2001 installation to the old 01-Dec-2000 installation, so that users don't have to change the URL.
Test your new 01-Dec-2001 installation under twiki/bin/2/view to make sure everything works as expected.
NOTE: Don't worry about the Plugins, they'll work after the switch.
Edit $TWIKIROOT/bin/2/TWiki.cfg and remove the /2 from $scriptUrlPath and $templateDir, ex:
$scriptUrlPath = "/twiki/bin"; $templateDir = "/home/httpd/twiki/templates";
Rename the TWiki2 web to TWiki, including attachments, ex:
cd $TWIKIROOT/data mv TWiki TWiki1 mv TWiki2 TWiki cd $TWIKIROOT/pub mv TWiki TWiki1 mv TWiki2 TWiki
Rename the templates2 directory to templates, ex:
cd $TWIKIROOT mv templates templates1 mv templates2 templates
Move the lib directory one level up from $TWIKIROOT/bin/lib to $TWIKIROOT/lib, ex:
cd $TWIKIROOT mv bin/lib .
Copy content of bin/2 to bin, ex:
cd $TWIKIROOT/bin cp -p bin/2/* . cp -p bin/2/.htaccess .
Point your browser to the original URL and make sure the relocated 01-Dec-2001 installation works as expected: check browsing, searching and user registration.
The EmptyPlugin, DefaultPlugin, and InterwikiPlugin should be preinstalled. To check the InterwikiPlugin, go to its page.
If you have customized the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE and extendGetRenderedVersionInsidePRE in twiki/bin/wikicfg.pm:
Merge those changes back into twiki/lib/TWiki/Plugins/Default.pm
General Format Changes
The format of the %GMTIME{"..."}% and %SERVERTIME{"..."}% variables is now "$hour:$min" instead of "hour:min". More in TWikiVariables.
ExtendingTableSyntax: Enhanced table syntax might have unwanted side effect: | *bold* | cells, | center aligned | and | right aligned | cells, span multiple columns using | empty cells |||. More in TextFormattingRules.
Use Net::SMTP module instead of sendmail if installed.
Use <verbatim> ... </verbatim> tags instead of <pre> ... </pre> tags where appropriate. More in TextFormattingRules.
New variable %STARTINCLUDE% and %STOPINCLUDE% variables to control what gets included of a topic. More in TWikiVariables.
Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.
Attachments are now under revision control: $attachAsciiPath in TWiki.cfg defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.
Handling for topic-specific templates like edit.new.tmpl has been removed and replaced by template topics in the new TWikiTemplates.
A new file warning.txt file can appear in the data directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.
If you are coming from a version earlier than the 01 May 2000 production release, please see TWikiUpgradeTo01May2000 first. For the latest version read TWikiUpgradeGuide.
The 01 Dec 2000 release has these changes that affect the upgrade of the 01 May 2000 version:
Improved search, i.e. search multiple webs.
The changes script has been retired (related to new search).
Reorganization of topics: The TWiki.Main web was split up into TWiki.Main and TWiki.TWiki web.
This upgrade is somewhat more labor intensive, mainly caused by splitting up the TWiki.Main web. Please note that subsequent updates will be much easier because user related topics (in TWiki.Main web) and TWiki related documents (in TWiki.TWiki web) have been separated.
These are the steps you need to perform to upgrade the 01 May 2000 version to the 01 Dec 2000 release: [ We assume export TWIKIROOT=/some/dir/ ]
Unpack the zip file into some working directory:
mkdir -p ~/tmp/ cd ~/tmp unzip ~/TWiki20001201.zip
Upgrade the TWiki document files ( twiki )
Move the document files to your TWiki root, i.e.
mv ~/tmp/TWiki*.html $TWIKIROOT mv ~/tmp/readme.txt $TWIKIROOT
Upgrade cgi-bin scripts ( twiki/bin )
Rename your original twiki/bin directory, i.e.
mv $TWIKIROOT/bin $TWIKIROOT/bin.old
Move the new scripts to your original twiki/bin location, i.e.
mv ~/tmp/bin $TWIKIROOT/bin
Merge the changes in your current wikicfg.pm into the new wikicfg.pm. We suggest using diff -c to compare the two files if you have made heavy changes to the file, i.e.
diff -c $TWIKIROOT/bin.old/wikicfg.pm $TWIKIROOT/bin/wikicfg.pm | less
Restore any additional scripts you might have from the old directory, i.e.
mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/ (Note that the changes script is obsolete.)
In case you have basic authentication:
The TWikiRegistration topic moved from the TWiki.Main web to the TWiki.TWiki web. Change .htaccess to reflect the new location, i.e.
ErrorDocument 401 /cgi-bin/view/TWiki/TWikiRegistration
Pay attention to the file and directory permissions (security issue)
Test your TWiki installation if you can view topics. (Ignore the %HTTP_EQUIV_ON_VIEW% you see on top of the topic; this will disappear after upgrading the template files.
Upgrade template files ( twiki/templates )
Rename your original twiki/templates directory, i.e.
mv $TWIKIROOT/templates $TWIKIROOT/templates.old
Move the new templates to your original twiki/templates location, i.e.
mv ~/tmp/templates $TWIKIROOT/templates
Merge the changes in your current template files into the new template files. To compare two files use
diff -c $TWIKIROOT/templates.old/view.tmpl $TWIKIROOT/templates/view.tmpl | less
Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
Test your TWiki installation if you can view topics.
Upgrade public files ( twiki/pub )
Move the new twiki/pub/TWiki directory to your installation, i.e.
mv ~/tmp/pub/TWiki $TWIKIROOT/pub/
Pay attention to the file permissions of the TWiki directory and its subdirectory and files. The files must be writable by the cgi-scripts (usually user "nobody")
Move the new twiki/pub/twikilogo* image files to your installation, i.e.
mv ~/tmp/pub/twikilogo* $TWIKIROOT/pub/
Upgrade data files ( twiki/data )
Move the new twiki/data/TWiki directory to your installation, i.e.
mv ~/tmp/data/TWiki $TWIKIROOT/data/ Pay attention to the file permissions of the TWiki directory and its files. The files must be writable by the cgi-scripts (usually user "nobody")
Optionally move the new twiki/data/Test directory to your installation, i.e.
mv ~/tmp/data/Test $TWIKIROOT/data/ (Pay attention to the file permissions)
Move these new TWiki.Main web topics to your TWiki.Main web: TWikiGroups, TWikiAdminGroup, and if needed also OfficeLocations , i.e.
mv ~/tmp/data/Main/TWikiGroups.* $TWIKIROOT/data/Main (Pay attention to the file permissions)
The following topics in the TWiki.Main web are obsolete and can be deleted: BillClinton, GoodStyle, RegularExpression, TextFormattingFAQ, TextFormattingRules, ManagingWebs, TWikiCategoryTable, TWikiEnhancementRequests, TWikiImplementationNotes, TWikiInstallationGuide, WebNotification, TWikiPlannedFeatures, TWikiUpgradeTo01May2000, TWikiUsernameVsLoginUsername, TWikiSite, WelcomeGuest, WelcomeVisitor, WikiName, WikiNotation, WikiTopic, WikiWikiClones. Sample delete command:
rm -f $TWIKIROOT/data/Main/BillClinton.*
The following topics are new and most be copied to all of your TWiki webs: WebChanges, WebIndex.
cp -p $TWIKIROOT/data/TWiki/WebChanges.txt* $TWIKIROOT/data/Main cp -p $TWIKIROOT/data/TWiki/WebIndex.txt* $TWIKIROOT/data/Main Repeat this for all your webs. Pay attention to the file permissions.
TWikiRegistration moved from TWiki.Main to TWiki.TWiki. In case you customized TWikiRegistration , merge your changes back into TWiki.TWikiRegistration , then delete $TWIKIROOT/data/Main/TWikiRegistration*.
TWikiPreferences moved from TWiki.Main to TWiki.TWiki. Merge your changes to TWikiPreferences into TWiki.TWikiPreferences.
Modify the WebPreferences topics in all your webs to reflect the following:
WEBTOPICLIST should use WebChanges for "Changes", and WebIndex for "Index", i.e.
| <a href="WebChanges">Changes</a> | <a href="WebIndex">Index</a>
In case you want to exclude a web from a web="all" search: Set this new preference
Set NOSEARCHALL = on
The WebSearch topic has considerable changes. Copy the one from TWiki.TWiki into all webs, or merge them if you made changes. To copy, do an edit-copy-edit-paste operation.
Change the WebHome topics in all your webs to reflect these changes:
The "Changes" link should point to WebChanges.
The "Topic index" link should point to WebIndex.
Change the include of the web table to %INCLUDE{"%TWIKIWEB%.TWikiWebsTable"}%
Merge your TWikiWebsTable topic in TWiki.Main with the TWikiWebsTable topic in TWiki.TWiki. Note the new variable to query the color of a web. Delete the old TWikiWebsTable topic in TWiki.Main after merge is complete.
The following topics in the TWiki.Main web are deprecated (because they moved to TWiki.TWiki), but still need to be present in TWiki.Main because of existing links to them: FileAttachment, TWikiDocumentation, TWikiHistory, TWikiPreferences, TWikiVariables.
It is recommended that you edit these topics in TWiki.Main and replace the content with this line:
This topic moved to %TWIKIWEB%.%TOPIC% in the %WIKITOOLNAME%.%TWIKIWEB% web.
In all your webs, change references to topics that moved to the TWiki.TWiki web:
Change topics: TWikiUsers , WebNotify , WebHome
With links to: TWikiPreferences , TWikiVariables , TWikiUsers , TWikiWebsTable and WelcomeGuest
TWiki Access Control
Read TWikiAccessControl, in case you want to use the new authorization feature based on groups.
To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things:
Back up your system.
Update the templates in the /templates directory (and its subdirs):
Take the templates of the latest distribution as the base and merge your changes back into it.
Update the Perl scripts in the /bin directory:
Take the scripts of the latest distribution as the base and merge your changes back into it. Do so also for wikicfg.pm because it has important changes as well.
Update topics:
Copy the new Main. TWikiPreferences? topic (and *,v file) into your TWiki.Main web. Customize the topic to your needs.
In case you are on an Intranet: Copy topic TWikiRegistration to Main.TWikiRegistration. Customize if needed.
In case you are on a public server: Copy topic TWikiRegistrationPub to Main.TWikiRegistration. Customize if needed.
Copy the Main. TWikiWebsTable topic (and *,v file) into your Main web and customize it. Reason: The new release does not use the *.inc include files anymore.
Optionally: Search for %INCLUDE%'s in all your webs and change them to the new %INCLUDE{"file.ext"}% syntax. Note: Your old %INCLUDE:"file.ext"% syntax still works (the legacy rule is defined in wikicfg.pm .)
TWiki site access control and user activity tracking
Overview
TWiki does not authenticate users internally, it depends on the REMOTE_USER environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).
TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.
Authentication Options
No special installation steps are required if the server is already authenticated. If it isn't, you have three standard options for controlling user access:
Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest? default identity, so you can't track individual user activity.
Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server.
Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit=, installpasswd, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.
Partial Authentication
Tracking by IP address is an experimental feature, enabled in lib/TWiki.cfg. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:
Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.
TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest?.
Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.
NOTE: This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.
Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:
This section applies only if your netfrag.org is installed on a server that is both authenticated and on an intranet.
netfrag.org internally manages two usernames: Login username and TWiki username.
Login username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to netfrag.org by the REMOTE_USER environment variable, and used by internally by netfrag.org. Login usernames are maintained by your system administrator.
TWiki username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the Main web.
netfrag.org can automatically map an intranet username to a TWiki username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.
NOTE:To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Main.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the netfrag.org.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.
Changing Passwords
Change and reset passwords using forms on regular pages. Use TWikiAccessControl to restrict use as required.
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
Request for reset of password
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will receive a page with yor new password appearing encrypted.
This section applies only if your netfrag.org is installed on a server that is both authenticated and on an intranet.
netfrag.org internally manages two usernames: Login username and TWiki username.
Login username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to netfrag.org by the REMOTE_USER environment variable. netfrag.org uses this name internally to log topic changes. Login usernames are maintained by your system administrator.
TWiki username: This is your name in WikiNotation, ex: PeterThoeny, recorded when you register in TWikiRegistration; doing so also generates your personal home page in the Main web of your TWiki site.
netfrag.org can map the intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic. This happens automatically when you register.
NOTE:To correctly enter a WikiName - your own or someone else's - be sure to specify the Main web in front of the Wiki username: write Main.WikiUsername or %MAINWEB%.WikiUsername. This assures that the name will be linked automatically to the netfrag.org.Main web, where user registration pages are stored, even if the text is entered in a different netfrag.org web.
Text strings expanded on the fly to display data or system info
Overview
TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. Variables are replaced by their actual values: stored data, or system info (like the date, or the current user). There are predefined variables, and Preference variables that you set. You can also define custom variables, with new names and values.
Predefined Variables
Most predefined variables return values that were either defined when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you control how the formatted results appear.
netfrag.org expands the following variables (enclosed in % percent signs):
Variable:
Expanded to:
%WIKIHOMEURL%
The base script URL of netfrag.org, is the link of the Home icon in the upper left corner, is http://TWiki.org/
%SCRIPTURL%
The script URL of netfrag.org, is http://netfrag.org/twiki/bin
%SCRIPTURLPATH%
The path of the script URL of netfrag.org, is /twiki/bin
%SCRIPTSUFFIX%
The script suffix, ex: .pl, .cgi is
%PUBURL%
The public URL of TWiki, is http://netfrag.org/twiki/pub
%PUBURLPATH%
The path of the public URL of netfrag.org, is /twiki/pub
%ATTACHURL%
The attachment URL of the current topic, is http://netfrag.org/twiki/pub/TWiki/TWikiVariables Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH%
The path of the attachment URL of the current topic, is /twiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}%
Returns the value of a URL parameter. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%WIKITOOLNAME%
Name of wiki tool, is netfrag.org
%WIKIVERSION%
Wiki tool version is 04 Sep 2004 $Rev: 1742 $
%USERNAME%
Your login username is guest
%WIKINAME%
Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is TWikiGuest
%WIKIUSERNAME%
Your %WIKINAME% including the Main web name. Usefull for signatures. Is Main.TWikiGuest
%MAINWEB%
The Main web containing TWikiUsers, OfficeLocations? and TWikiGroups?. Is Main
%TWIKIWEB%
The web containing all documentation and configuration of netfrag.org is TWiki
%WEB%
The current web is TWiki
%BASEWEB%
The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
%INCLUDINGWEB%
The web name of the topic that includes the current topic. Same as %WEB% in case there is no include.
The index topic of all registered users. Is TWikiUsers
%WIKIPREFSTOPIC%
The web preferences topic. Is TWikiPreferences
%WEBPREFSTOPIC%
The web preferences topic. Is WebPreferences
%STATISTICSTOPIC%
The web statistics topic. Is WebStatistics
%TOPIC%
The current topic name, is TWikiVariables
%BASETOPIC%
The name of the topic where the includes started, e.g. the first topic of nested includes. Same as %TOPIC% in case there is no include.
%INCLUDINGTOPIC%
The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC%
The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}%
Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
Parameters are format, separator and web:
Format of one line, may include $name and $web variables
"$name"
format="format"
(Alternative to above)
"$name"
separator=", "
line separator
"\n" (new line)
web="Name"
Name of web
Current web
Examples:
%TOPICLIST{" * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}%
Web index, e.g. list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
Parameters are format, separator and web:
comma sep list of Web, public expands to all non-hidden
"public"
marker="selected"
Text for $marker where item matches selection, otherwise equals ""
"selected"
selection="%WEB%"
Current value to be selected in list
section="%WEB%"
Examples: %WEBLIST{" * [[$name.Home]]"}% creates a bullet list of all webs.
%WEBLIST{"" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
Variables can be shortened to 3 characters. Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% is 27 Apr, 2024 - 10:56:16
%SERVERTIME%
Server time, is 27 Apr 2024 - 12:56
%SERVERTIME{"format"}%
Formatted server time. Example: %SERVERTIME{"$hou:$min"}% is 12:56
%HTTP_HOST%
HTTP_HOST environment variable, is netfrag.org
%REMOTE_ADDR%
REMOTE_ADDR environment variable, is 3.15.202.4
%REMOTE_PORT%
REMOTE_PORT environment variable, is 31100
%REMOTE_USER%
REMOTE_USER environment variable, is
%INCLUDE{"page" ...}%
Server side include to IncludeTopicsAndWebPages. Parameters are page name, and an optional pattern="(reg-exp)". The page name is:
"SomeTopic"
The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
"Web.Topic"
A topic in another web, i.e. %INCLUDE{"TWiki.TWikiWebsTable"}%
"http://..."
A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%
%STARTINCLUDE%
If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE%
If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC%
Table of Contents of current topic.
%TOC{"SomeTopic" ...}%
Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text<h2>") are taken into account. (But not "<H2>text</H2>", which can be used to exclude a heading from the TOC.) Parameters are topic name, web and depth:
What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searcing for topics that have a specific parent i.e. its children
required
web="%WEB%"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs.
required
topic="%TOPIC%"
The topic the search relates to
required
title="Title"
Text the is pre-pended to any search results
required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}%
Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #444444
[1] Note: The search form uses identical names for input fields.
[2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences.
Preferences Variables
Additional variables are defined in the preferences ( site-level ( SL ) in TWikiPreferences, web-level ( WL ) in WebPreferences of each web, and user level ( UL ) preferences in individual user topics):
Variable:
Level:
What:
%WIKIWEBMASTER%
SL
Webmaster email address (sender of email notifications) , is webmaster@netfrag.org
%WIKIWEBLIST%
SL
List of netfrag.org webs (in upper right corner of topics)
%WEBTOPICLIST%
WL
Common links of web (second line of topics)
%WEBCOPYRIGHT%
SL , WL
Copyright notice (bottom right corner of topics)
%WEBBGCOLOR%
WL
Background color of web
%NOSEARCHALL%
WL
Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR%
SL , UL
Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR%
SL , UL
Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH%
SL , UL
Horizontal size of edit box, is 100
%EDITBOXHEIGHT%
SL , UL
Vertical size of edit box, is 20
%RELEASEEDITLOCKCHECKBOX%
SL , UL
Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is: checked
%DONTNOTIFYCHECKBOX%
SL , UL
Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty. Value is: checked
%ATTACHLINKBOX%
SL , UL
Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is:
%HTTP_EQUIV_ON_VIEW%
SL
http-equiv meta tags for view, rdiff, attach, search* scripts.
%HTTP_EQUIV_ON_EDIT%
SL , UL
http-equiv meta tags for edit script.
%HTTP_EQUIV_ON_PREVIEW%
SL , UL
http-equiv meta tags for preview script.
%DENYWEBCHANGE%
WL
List of users and groups who are not allowed to change topics in the netfrag.org web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE%
WL
List of users and groups who are allowed to change topics in the netfrag.org web. (More in TWikiAccessControl)
%DENYTOPICCHANGE%
(any topic)
List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE%
(any topic)
List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME%
WL
List of users and groups who are not allowed to rename topics in the netfrag.org web. (More in TWikiAccessControl)
%ALLOWWEBRENAME%
WL
List of users and groups who are allowed to rename topics in the netfrag.org web. (More in TWikiAccessControl)
%DENYTOPICRENAME%
(any topic)
List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME%
(any topic)
List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES%
SL , WL
List of preferences that are not allowed to be overridden by next level preferences
Setting Preferences
The syntax for Preferences variables is the same anywhere in TWiki. In Edit mode, from the start of a new line: [6 spaces] * [space] Set [space] VARIABLENAME [space] = [value] Example:
Set VARIABLENAME = value
Creating Custom Variables
You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.
Example: Create a custom logo variable
To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif
TWiki.TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TWiki.TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Table with form field values of topics with a form
Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
Creating Custom Variables
You can add your own preference variables for an entire site, a single web, or a single topic, using the standard syntax. Whatever you include in your variable will be expanded on display, and treated exactly as if it had been written out. So you can place formatted text, page links, image paths.
Example: Create a custom logo variable
To place a logo anywhere in a web by typing %MYLOGO%, simply define the variable on the web's WebPreferences page. You also have to upload logo.gif - this can be done by attaching a file to LogoTopic (any topic name you choose):
Set MYLOGO = %PUBURL%/%MAINWEB%/LogoTopic/logo.gif
Sandbox test area with all features enabled.
[ Changes?
| Search?
]
Experiment in an unrestricted hands-on web.
You can use color coding by web for identification and reference. Contact webmaster@netfrag.org if you need a separate collaboration web for your team. New TWiki webs can be added easily. To modify this table: { View | Edit }
Changing table properties like border width, cell spacing and cell padding
Changing background color for header cells
Changing background color for data cells - colors can alternate
Behaviour can be specified for a specific table using %TABLE{...}% or with global preferences
TablePlugin Global Settings
Plugin settings are stored as preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, for example, %INTERWIKIPLUGIN_SHORTDESCRIPTION%
Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns
Set DEBUG to 1 to get debug messages in data/debug.txt. Default: 0
Set DEBUG = 0
Table border width. Default: 1
Set TABLEBORDER = 1
Table cell padding. Default: 0
Set CELLPADDING = 0
Table cell spacing. Default: 1
Set CELLSPACING = 1
Vertical alignment of cells. Set to: top, middle, bottom or baseline; default: (empty)
Set VALIGN =
Table header cell alignment. Set to: left, center, right or justify; default: (empty)
Set HEADERALIGN =
Table data cell alignment. Set to: left, center, right or justify; default: (empty)
Set DATAALIGN =
Color for header cells ('*'s around text). Default: #99CCCC
#Set HEADER_BG = red
Background color for table rows, two alternate colors. Default: #FFFFCC,#FFFFFF
#Set DATA_BG = #FFFFCC,#FFFFFF
Set DATA_BG =
Make sortable:
#Set SORT = attachments
Set SORT = all
#Set SORT = none
Sorting
Click on column heading text to sort by a column. Initial column will be sorted in descending order, click again to get ascending order. The type of data in the cell is determined automatically:
date if format is:
dd MMM YYY - hh:mm
dd-MMM-YY or dd-MM-YYYY (can be / or space in place of -)
13 Mar 2002 PTh: Added TWiki:Main/ShawnBradford's initsort and initdirection 12 Mar 2002 PTh: Added valign, headeralign and dataalign; fixed bug of swapped cellpadding/cellspacing; fixed warning of uninitialized value 05 Jan 2002 PTh: Fixed sorting bug of cells with leading white space 06 Dec 2001 PTh: Fixed date sorting bug 03 Dec 2001 PTh: Fixed sort="off" bug and more 29 Nov 2001: PTh fixed Perl warnings 16 Nov 2001: PTh added table border, cell spacing, cell padding, gif files 07 Oct 2001: Initial version
Text Formatting FAQ
The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system on one quick reference page.
Create a separator - a horizontal rule - by entering three dashes at the beginning of a blank line: ---. You can enter more than three if you like, for a more visible separator in edit mode: --------------
How do I create a heading?
You can create six sizes of headings - <h1>...<h6> in HTML - by typing, from the beginning of a line, three dashes (-), from one to six plus signs (+), a space, and your heading text. The FAQ questions on this page are created with: ---+++ Have a question?.
You can insert a nested table of contents, generated from headings, by placing %TOC% wherever you like on a page (see TWikiVariables for more %TOC% options).
Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
TWiki interprets text as HTML, and the '<' and '>' characters define where HTML commands start and end. Text inside angle brackets is treated as HTML, and ignored if it doesn't actually do anything - either way, the brackets and its contents are not displayed.
If you want to display angle brackets, enter them as HTML codes instead of typing them in directly:
< = < > = >
You enter:(a > 0)Result:(a > 0)
Some words appear highlighted, with a "?" link at the end. How can I prevent that?
A question mark after a word is a link to a topic that doesn't yet exist - click it to create the new page. This is a TWiki feature - typing a MeaningfulTitle? in a comment is an invitation for someone else to add a new branch to the topic.
To prevent auto-linking - say you want to enter a word like JavaScript (the proper spelling!) - prefix the WikiStyleWord? with the special TWiki HTML tag <nop>:
<nop>WikiStyleWord displays as WikiStyleWord
How can I write fixed font text?
The quickest way is to enclose the text in equal signs:
Text I enter gets wrapped around. How can I keep the formatting as it is?
TWiki interprets text as HTML, so you can use the preformatted HTML option to keep the new line of text as is. Enclose the text in <pre> </pre>, or in TWiki's own <verbatim> </verbatim> tag:
This text will keep its format as it is:
<verbatim>
Unit Price Qty Cost
------- ------ --- ------
aaa 12.00 3 36.00
</verbatim>
The pre tag is standard HTML; verbatim is a special TWiki tag that forces text to fixed font mode, and also prevents other tags and TWiki shortcuts from being expanded.
2. Use HTML tables with <table>, <tr>, <td> tags
This is a manual process using HTML commands.
You enter:
<table border="1">
<tr>
<th> Head A </th> <th> Head B </th>
</tr><tr>
<td> Cell A2 </td> <td> Cell B2 </td>
</tr><tr>
<td> Cell A3 </td> <td> Cell B3 </td>
</tr>
</table>
Result:
Head A
Head B
Cell A2
Cell B2
Cell A3
Cell B3
3. Use preformatted text with <verbatim> tags
See "Text enclosed..."?
Can I include images on a page?
Yes. The easiest way is to attach a GIF, JPG or PNG file to a topic and then to place it with: %ATTACHURL%/myImage.gif. This works only for the page that the image is attached to.
To place an image on any page, ther are two ways of including inline images.
1. Using URL ending in .gif, .jpg, .jpeg, .png
This is a simple and automatic way of including inline images. Simply write the URL of the image file, this will create the inline image for you. NOTE: The images must be accessible? as a URL.
You enter: TWiki http://netfrag.org/twiki/pub/wikiHome.gif logo. Result: TWiki logo.
You can upload images directly to your server with FTP access. You can also attach image files to a topic - you could even create a dedicated image topic, like ImageLibrary - and then link to the images directly:
Attach pic.gif to Someweb.SomeTopic
Display with http://netfrag.org/twiki/pub/Someweb/SomeTopic/pic.gif
2. Using <img> tag
This is a manual process where you have more control over the rendering of the image. Use the <img> tag of HTML to include GIF, JPG and PNG files. Note: The display of the topic is faster if you include the WIDTH and HEIGHT parameters that have the actual image size. http://www.htmlhelp.com/reference/wilbur/special/img.html has more on inline images.
Sure. The quickest way is to go <font color="colorCode">colorize</font> - font is an HTML tag that works in any browser, although it's been phased out in the latest HTML specs.
You can also use the up-to-date style attribute - ex: style="color:#ff0000" - placed in most HTML tags. span is an all-purpose choice: "<span style="color:#ff0000">CoLoR</span>. Only old (like 3.x IE & NS) browsers have a problem with style.
"colorCode" is the hexadecimal RGB color code, which is simply Red, Green and Blue values in hex notation (base 16, 0-F). For pure red, the RGB components are 255-0-0 - full red (255), no green or blue. That's FF-0-0 in hex, or "#ff000=" for Web page purposes. For a basic color selection (you can StandardColor names instead of hex code in the =font tag only):
Black:
"#000000"
Green:
"#008000"
Silver:
"#c0c0c0"
Lime:
"#00ff00"
Gray:
"#808080"
Olive:
"#808000"
White:
"#ffffff"
Yellow:
"#ffff00"
Maroon:
"#800000"
Navy:
"#000080"
Red:
"#ff0000"
Blue:
"#0000ff"
Purple:
="#800080"=
Teal:
"#008080"
Fuchsia:
"#ff00ff"
Aqua:
"#00ffff"
You enter: <font color="#ff0000"> Red color </font> draws attention.
Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all layed out below - refer back to this page in a pop-up window from the Edit screen.
TWiki Editing Shorthand
Formatting Command:
Example: You write:
You get:
Paragraphs:
Blank lines will create new paragraphs.
1st paragraph
2nd paragraph
1st paragraph
2nd paragraph
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables.
---++ Sushi
---+++ Maguro
Sushi
Maguro
Bold Text:
Words get bold by enclosing them in * asterisks.
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores.
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
=Fixed font=
Fixed font
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
==Bold fixed==
Bold fixed
Note: Make sure to "stick" the * _ = == signs to the words, e.g. take away spaces.
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted. Note: Each tag must be on a line by itself.
Separator:
At least three dashes at the beginning of a line.
-------
List Item:
Three spaces and an asterisk.
* bullet item
bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
* nested stuff
nested stuff
Ordered List:
Three spaces and a number.
1 Sushi
1 Dim Sum
Sushi
Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition. Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the non-breaking-space entity.
Sushi: Japan
Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars. Note:| *bold* | cells are rendered as table headers. Note:| spaced | cells are rendered center aligned. Note:| spaced | cells are rendered right aligned. Note:| 2 colspan || cells are rendered as multi-span columns. Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different netfrag.org web write Webname.TopicName.
#SquareBrackets
Forced Links:
You can create a forced internal link by enclosing words in double square brackets. Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].
Anchors:
You can define a link reference inside a netfrag.org topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
[[WebHome#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS
Using HTML
You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
HTML and TWiki Usability
On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand? instead - this keeps the text uncluttered and easy to edit.
NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
TWiki HTML Rendering
TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
NOTE: The opening and closing angle brackets - <...> - of an HTML tag must be on the same line, or the tag will be broken.
This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, <, ex: a > b
If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
Hyperlinks
Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
Internal Links
GoodStyle is a WikiWord that links to the GoodStyle topic located in the current netfrag.org web.
NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
External Links
http://..., https://..., ftp://... and mailto:...@... are linked automatically.
Email addresses like name@domain.com are linked automatically.
[[Square bracket rules]] let you easily create non-WikiWord links?.
TWikiPlugin Formatting Extensions
Plugins provide additional text formatting capabilities and can extend the functionality of netfrag.org into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.
Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
HeadlinesPlugin: Build news portals that show headline news based on RSS news feeds from news sites.
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
TablePlugin: Control attributes of tables and sorting of table columns
VisualConfirmPlugin: Plugin for visual confirmation of new user registration.
Check on current Plugin status and settings for this site in TWikiPreferences.
-- MikeMannix? - 02 Dec 2001
Topics get locked for some time (default is one hour) whenever a user edits, previews or saves a topic. This is to prevent simultaneous topic updates. There is a lock warning if another users tries to edit a topic while the lock is still on.
You can remove the lock by checking the "Release edit lock" checkbox in preview. This is a way to let other people know that you are done with your editing. Note: Please remember not to go back in your browser in case you checked the box and after that you decide to do more changes to the topic. Instead press the Edit link to re-edit your page.
Note: The "Cancel edit" link in edit mode lets you cancel out of an edit session without saving any changes. It also releases the edit lock, so that other people don't get the lock warning.
Note: The initial state of the checkbox can be set to on with the RELEASEEDITLOCKCHECKBOX preferences variable. See TWikiPreferences for more.
Plugin for visual confirmation of new user registration, to prevent automated scripts to create users and spam your wiki with their url's to get a better google ranking.
Set SHORTDESCRIPTION = Plugin for visual confirmation of new user registration.
Debug plugin: (See output in data/debug.txt)
S et DEBUG = 1
Custom settings (defaults shown):
Characters to use in generated strings:
Set CHARACTERS = ABCDEFGHKLMNPRSTVWXYZabcdeghpqsuvwxy@
Truetype font to use:
Set FONT = luxisbi.ttf
Number of random lines to add (use none for 0):
Set LINES = 10
Number of random circles to add (use none for 0):
Set CIRCLES = 5
Noise, percentage of pixels to flip randomly after generating graphics (use none for 0%):
Set NOISE = 10
Plugin Installation Instructions
Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
Download the ZIP file from the Plugin web (see below)
Unzip VisualConfirmPlugin.zip in your twiki installation directory. Content:
Apply the patch register.patch to bin/register (alternatively, patch register manual, see section below):
cd bin
patch < ../register.patch
Create the directories visualconfirm and visualconfirm/db in your pub/ directory, and make sure it is readable and writable by the user that TWiki is executing as.
mkdir -p pub/visualconfirm/db
chown -R nobody pub/visualconfirm
chmod -R 644 pub/visualconfirm
Restrict access to the database files, for example, by including the following in your httpd.conf:
<Directory "/path/to/twiki/pub/visualconfirm/db">
deny from all
</Directory>
Make sure the plugin has access to the preferred truetype font, by putting the .ttf file in pub/visualconfirm/
Test if the installation was successful:
Create a topic containing <IMG SRC="%VISUALCONFIRMURL%"> and %VISUALCONFIRMHASH%
When loading this topic you should see an obfuscated character string loaded as a png and a hexadecimal hash.
Display the image %VISUALCONFIRMURL% somewhere in your form, along with a text instructing new users to copy the obfuscated text into the appropriate text input.
Add the appropriate text input as Twk1VisualConfirm
Since wabi-sabi represents a comprehensive Japanese world view or aesthetic system, it is difficult to explain precisely in western terms. According to Leonard Koren, wabi-sabi is the most conspicuous and characteristic feature of what we think of as traditional Japanese beauty and it "occupies roughly the same position in the Japanese pantheon of aesthetic values as do the Greek ideals of beauty and perfection in the West."
Wabi-sabi is a beauty of things imperfect, impermanent, and incomplete. It is the beauty of things modest and humble. It is the beauty of things unconventional.
The concepts of wabi-sabi correlate with the concepts of Zen Buddhism, as the first Japanese involved with wabi-sabi were tea masters, priests, and monks who practiced Zen. Zen Buddhism originated in India, traveled to China in the 6th century, and was first introduced in Japan around the 12th century. Zen emphasizes "direct, intuitive insight into transcendental truth beyond all intellectual conception." At the core of wabi- sabi is the importance of transcending ways of looking and thinking about things/existence.
Statistics for TWiki.TWiki Web Month: Topic views: Topic saves: File uploads: Most popular topic views: Top contributors for topic save and uploads: Apr 2024 31572 ...
VisualConfirmPlugin Plugin for visual confirmation of new user registration, to prevent automated scripts to create users and spam your wiki with their url's to get ...
RSS Feed This is the base for the RSS feed for each web. Each web has a WebRss that should contain the following text: TWiki's INCLUDINGWEB web SCRIPTURL /view SCRIPTSUFFIX ...
TWiki Site-Level Preferences The following settings are site-level preferences , e.g. affecting all users in all TWiki webs. These preferences can be overwritten ...
Inter-Wiki Link Rules (or Links to other Sites) This topic lists all aliases needed to map Inter-Site links to external wikis/sites. Whenever you write ExternalSite ...
SingletonWikiWordPlugin This designates that a single word is a reference to a single word. To show TWiki that it should be linked to, write a dot before it. Hence ...
To edit pages on this TWiki Collaborative Web, you must have a registered user name and password. Note: You can also login anonymously as user TWikiGuest with password ...
TOC STARTINCLUDE ## File Attachments Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments ...
TOC STARTINCLUDE # TWiki Formatted Search Results Inline search feature allows flexible formatting of search result Overview By default, the format for displaying ...
TOC STARTINCLUDE # TWiki Access Control Restricting read and write access to topics and webs, by users and groups Overview TWikiAccessControl allows you restrict ...
GoodStyle Collaboration Tips TWiki has a very simple text formatting shorthand . In any case, you won't go wrong if you simply: start each line without spaces separate ...
Hide/Unhide Attachments You can hide/unhide file attachments. In the FileAttachment table, click on an action link, enable the Hide file checkbox, then click Change ...
FAQ: How do I delete or rename a topic? Answer: New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously ...
TOC STARTINCLUDE # Managing Topics Browser-based rename, move, and delete for individual topics Overview Use browser controls while viewing a topic, to change its ...
Default TWiki Plugin The default plugin is used for some deprecated rendering of older TWiki versions and of JosWiki. This plugin can also be used to specify some ...
TOC STARTINCLUDE #FileSystem # Appendix A: TWiki File System Annotated listings of files included in the 01-Sep-2001 TWiki distribution Overview This Appendix contains ...
TOC STARTINCLUDE # Managing Webs Adding, renaming and deleting webs are manual operations done directly on the server Overview Managing TWiki webs requires direct ...
Request for reset of password Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank ...
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you. Your TWIKIWEB ...
TOC STARTINCLUDE ## Site Usage Statistics You can automatically generate usage statistics for all webs. To enable this: Make sure variable $doLogTopicView, $doLogTopicSave ...
FAQ: What happens if two of us try to edit the same topic simultaneously? Answer: The second person gets a warning that the topic is currently being edited by another ...
FAQ: I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer: That is an indication ...
FAQ: TWiki has a GPL (GNU General Public License). What is GPL? Answer: TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of ...
FAQ: Why does the topic revision not increase when I edit a topic? Answer: The same topic revision will be used when you save a topic again within a certain time ...
STARTINCLUDE ## Meta Data Rendering Various meta data can be stored in topics MetaDataDefinition This is rendered using the META variable. This is mostly used in ...
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute include h then the attachment is ...
InterwikiPlugin The InterwikiPlugin links ExternalSite:Page text to external sites based on aliases defined in the TWIKIWEB .InterWikis topic. This plugin is inspired ...
Empty TWiki Plugin This is an empty plugin you can use as a template to build your own TWIKIWEB .TWikiPlugins. This plugin does nothing, but is ready to be used. ...
Use the "Minor changes, don't notify" checkbox in preview in case you only make a minor change to a topic and you do not want to inform everybody who is on the WebNotify ...
Include Topics and Web Pages Using INCLUDE{...} Variable Use the INCLUDE{...} variable to embed the content of another topic or web page inside a TWiki topic. The ...
Background Image for Preview Preview looks like the real page, but the links leed to an oops dialog warning users of not yet saved topics. In addition, a background ...
Peter Thoeny is the author of TWiki and therefore a TWikiContributor and a core team member. See Main.PeterThoeny and http://TWiki.org/cgi-bin/view/Main/PeterThoeny ...
Welcome to TWiki, a flexible, powerful, and simple Web-based collaboration platform. Use TWiki to run a project development space, a document management system, a knowledge base, or any other groupware tool, on an intranet or on the Web.
This is the place to learn about it, download it, and try it out for yourself...
Frequent users should also browse the TWiki Reference Manual?!
It's easy to customize the User's Guide to reflect the features and settings enabled on your own TWiki site.
TWiki Reference Manual
Documentation for webmasters, system administrators, project managers, team leaders,
and all other users of the TWiki advanced online collaboration tool.
TWikiSiteTools include utilities for navigating and keeping up with site activity on individual TWiki webs. Preferences can also be configured, by web or site-wide. You are currently in the TWiki web.
Sandbox test area with all features enabled.
[ Changes?
| Search?
]
Experiment in an unrestricted hands-on web.
You can use color coding by web for identification and reference. Contact webmaster@netfrag.org if you need a separate collaboration web for your team. New TWiki webs can be added easily. To modify this table: { View | Edit }
TOC STARTINCLUDE #FileSystem # Appendix A: TWiki File System Annotated listings of files included in the 01-Sep-2001 TWiki distribution Overview This Appendix contains ...
BookView is part of search. It allows you to display the result in book view, e.g. the whole content of topcis is shown instead of a topic summary. This allows you ...
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you. Your TWIKIWEB ...
Default TWiki Plugin The default plugin is used for some deprecated rendering of older TWiki versions and of JosWiki. This plugin can also be used to specify some ...
FAQ: How do I delete or rename a topic? Answer: New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously ...
Use the "Minor changes, don't notify" checkbox in preview in case you only make a minor change to a topic and you do not want to inform everybody who is on the WebNotify ...
FAQ: Why does the topic revision not increase when I edit a topic? Answer: The same topic revision will be used when you save a topic again within a certain time ...
Empty TWiki Plugin This is an empty plugin you can use as a template to build your own TWIKIWEB .TWikiPlugins. This plugin does nothing, but is ready to be used. ...
TOC STARTINCLUDE ## File Attachments Each topic can have files attached to it, similar to an email attachment. Use your browser to upload or download a file. Attachments ...
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute include h then the attachment is considered ...
TOC STARTINCLUDE # TWiki Formatted Search Results Inline search feature allows flexible formatting of search result Overview By default, the format for displaying ...
FAQ: TWiki has a GPL (GNU General Public License). What is GPL? Answer: TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of ...
GoodStyle Collaboration Tips TWiki has a very simple text formatting shorthand . In any case, you won't go wrong if you simply: start each line without spaces separate ...
Headlines Plugin This plugin displays RSS feeds from news sites. Use it to build news portals that show headline news. Note: Syndic8.com ( http://www.syndic8.com ...
HEY! We asked you to not click any question mark links! Good thing we faked that one! You can use your browser's back button or key to get back to the tutorial. : ...
Hide/Unhide Attachments You can hide/unhide file attachments. In the FileAttachment table, click on an action link, enable the Hide file checkbox, then click Change ...
Include Topics and Web Pages Using INCLUDE{...} Variable Use the INCLUDE{...} variable to embed the content of another topic or web page inside a TWiki topic. The ...
Inter-Wiki Link Rules (or Links to other Sites) This topic lists all aliases needed to map Inter-Site links to external wikis/sites. Whenever you write ExternalSite ...
InterwikiPlugin The InterwikiPlugin links ExternalSite:Page text to external sites based on aliases defined in the TWIKIWEB .InterWikis topic. This plugin is inspired ...
TOC STARTINCLUDE # Managing Topics Browser-based rename, move, and delete for individual topics Overview Use browser controls while viewing a topic, to change its ...
TOC STARTINCLUDE # Managing Webs Adding, renaming and deleting webs are manual operations done directly on the server Overview Managing TWiki webs requires direct ...
STARTINCLUDE ## Meta Data Rendering Various meta data can be stored in topics MetaDataDefinition This is rendered using the META variable. This is mostly used in ...
Peter Thoeny is the author of TWiki and therefore a TWikiContributor and a core team member. See Main.PeterThoeny and http://TWiki.org/cgi-bin/view/Main/PeterThoeny ...
Php Plugin Describe Php Plugin: a b c PhpPlugin Global Settings Plugin settings are stored as preferences variables. To reference a plugin setting write plugin setting ...
Background Image for Preview Preview looks like the real page, but the links leed to an oops dialog warning users of not yet saved topics. In addition, a background ...
Regular expressions (REs), unlike simple queries, allow you to search for text which matches a particular pattern. REs are similar to (but more poweful than) the ...
Request for reset of password Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank ...
FAQ: I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer: That is an indication ...
FAQ: What happens if two of us try to edit the same topic simultaneously? Answer: The second person gets a warning that the topic is currently being edited by another ...
SingletonWikiWordPlugin This designates that a single word is a reference to a single word. To show TWiki that it should be linked to, write a dot before it. Hence ...
TOC STARTINCLUDE ## Site Usage Statistics You can automatically generate usage statistics for all webs. To enable this: Make sure variable $doLogTopicView, $doLogTopicSave ...
The 256 Standard Colors This table can be used to choose a color in WEBPREFSTOPIC of each web. 000000 000033 000066 000099 0000CC 0000FF 003300 003333 003366 003399 ...
TOC STARTINCLUDE # TWiki Access Control Restricting read and write access to topics and webs, by users and groups Overview TWikiAccessControl allows you restrict ...
TWiki Contributor A TWiki contributor is a person devoting his/her time to contribute on the development of the Open Source project TWiki, hosted at http://TWiki ...
FAQ: I would like to install TWiki on my server. Can I get the source? Answer: TWiki is distributed under the GnuGeneralPublicLicense. You can request the source ...
Please add enhancement request at the TWiki home at http://TWiki.org/cgi-bin/view/Codev/FeatureEnhancementRequest Related Topics TWikiHistory has a list of added ...
Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TOC STARTINCLUDE # TWiki Forms Form-based input in topics, with name/value pairs stored as Meta Data variables; multiple forms per web topic Overview By adding form ...
TOC STARTINCLUDE # TWiki Glossary TWiki uses a handful of general computer and Internet terms in a TWiki-specific way. This could get confusing, but it actually works ...
TOC STARTINCLUDE # TWiki System Requirements Server and client system requirements for TWiki 01-Sep-2001 Overview Maintaining minimum client and server requirements ...
TOC STARTINCLUDE # TWiki Installation Guide Installation instructions for the TWiki 01-Sep-2001 production release Overview These installation steps are based on ...
TOC STARTINCLUDE #MetaDataDefinition # TWiki Meta Data Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs Overview ...
INCLUDE{"DocsUserNote"} TWiki Pages TOC Each page in a TWiki web is called a topic , defined by its meaningful, descriptive TWIKIWEB .WikiWord title. Page Features ...
Planned features are listed up at the TWiki home at http://TWiki.org/cgi-bin/view/Codev/FeatureToDo Features currently under construction are at http://TWiki.org ...
TOC STARTINCLUDE # TWiki Plugins Plug-in enhanced feature add-ons, with a Plugin API for developers Overview You can add Plugins to extend TWiki's functionality, ...
TWiki Site-Level Preferences The following settings are site-level preferences , e.g. affecting all users in all TWiki webs. These preferences can be overwritten ...
To edit pages on this TWiki Collaborative Web, you must have a registered user name and password. Note: You can also login anonymously as user TWikiGuest with password ...
To edit pages on this TWiki Collaborative Web, you must have a registered user name and password. Note: You can also login anonymously as user TWikiGuest with password ...
TOC{depth "4"} STARTINCLUDE TWiki Shorthand Working in TWiki is as easy as typing in text exactly like email. You don't need to know HTML, though you can use it ...
TWiki is a Web-based collaboration platform A TWiki site is a easy-to-use, full-featured open communication environment: people anywhere on the Web or on an intranet ...
TOC STARTINCLUDE # TWikiSiteTools Utilities for searching, navigation, and monitoring site activity Overview TWikiSiteTools include utilities for navigating, searching ...
TOC STARTINCLUDE # TWiki Skins Skins overlay regular templates with alternate header/footer layouts; topic text is not affected Overview Skins are customized TWikiTemplates ...
TOC STARTINCLUDE # TWiki Templates Definition of the templates used to render all HTML pages displayed in TWiki Overview The new modular template system offers flexible ...
TOC STARTINCLUDE # 20-Minute TWiki This step-by-step, hands-on tutorial gets you up to speed with all the TWikiSite basics, in mere minutes ... 1. Get set... Open ...
TOC STARTINCLUDE # TWiki Upgrade Guide Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release) Overview This guide ...
## TWiki Upgrade Notes for Version 01 May 2000 If you are coming from a version earlier than the 01 May 2000 production release, please see TWikiUpgradeTo01May2000 ...
To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things: Back up your system. Update the templates in the /templates ...
TOC STARTINCLUDE # TWiki User Authentication TWiki site access control and user activity tracking Overview TWiki does not authenticate users internally, it depends ...
## TWiki Username vs. Login Username This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet . TWiki internally ...
TOC STARTINCLUDE # TWiki Variables Text strings expanded on the fly to display data or system info Overview TWikiVariables are text strings VARIABLE that expand ...
TWiki webs currently online: Use to: TWiki. MAINWEB Welcome to TWiki... Users, Groups, Offices tour this expandable virtual workspace. Changes Search Get a first ...
Table Plugin Gives extra control of table display: Allows sorting Changing table properties like border width, cell spacing and cell padding Changing background color ...
Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
TOC{depth "4"} STARTINCLUDE TWiki Text Formatting Working in TWiki is as easy as typing in text exactly like email. You don't need to know HTML, though you can use ...
Topics get locked for some time (default is one hour) whenever a user edits, previews or saves a topic. This is to prevent simultaneous topic updates. There is a lock ...
VisualConfirmPlugin Plugin for visual confirmation of new user registration, to prevent automated scripts to create users and spam your wiki with their url's to get ...
Since wabi-sabi represents a comprehensive Japanese world view or aesthetic system, it is difficult to explain precisely in western terms. According to Leonard Koren ...
SEARCH{". " web " INCLUDINGWEB " regex "on" nosearch "on" order "modified" reverse "on" limit "50"} See 100, 200, 400, 800 most recent changes See all changes
INCLUDE{"DocsUserNote"} Web Changes Notification Service Each TWiki web has an automatic email notification service that sends you an email with links to all of the ...
Welcome to TWiki, a flexible, powerful, and simple Web-based collaboration platform. Use TWiki to run a project development space, a document management system, a ...
NOTIFYTOPIC is a subscription service to be automatically notified by email when topics change in the TWiki.TWiki web. This is a convenient service, so you do not ...
TWiki.TWiki Web Preferences The following settings are web preferences of the TWiki.TWiki web. These preferences overwrite the site-level preferences in TWIKIWEB ...
RSS Feed This is the base for the RSS feed for each web. Each web has a WebRss that should contain the following text: TWiki's INCLUDINGWEB web SCRIPTURL /view SCRIPTSUFFIX ...
Simple search: Topic text (body) All webs (not only TWiki. INCLUDINGWEB web) Topic name TWIKIWEB .BookView Advanced search: Topic text (body) Search all public INCLUDINGWEB ...
Statistics for TWiki.TWiki Web Month: Topic views: Topic saves: File uploads: Most popular topic views: Top contributors for topic save and uploads: Apr 2024 31572 ...
NOTE: This Wiki topic does not exist WARNING: It is not recommended to use this topic name, because it will not be linked automatically. See TWIKIWEB .WikiWord for ...
NOTE: This Wiki topic does not exist yet If you would like to create this page: Simply click on the Create link at the bottom of this page. If you used the "Go" feature ...
Welcome WIKIUSERNAME , You have reached a TWikiSite (pronounced twee-kee site). TWiki is a meeting place where people collaborate on common interests. Anyone can contribute ...
FAQ: So what is this WikiWiki thing exactly? Answer: A set of pages of information that are open and free for anyone to edit as they wish. They are stored on a server ...
FAQ: Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer: TWiki is one of many WikiWikiClones, the first one was built by Ward Cummingham ...
Your name in WikiNotation. Usually your first and last name connected togther. For example, Bill Clinton's WikiName is BillClinton. Note: All users are in the TWiki ...
References on Wiki and Collaboration Some useful articles and books around collaboration and the Wiki technology in particular. Wiki Technology and TWiki Book: The ...
# TWikiShorthand Basics If you can enter text, you're ready for TWiki. With a few simple, intuitive TWikiShorthand rules, you'll be able to use plain text to create ...
TWiki is a Wiki Wiki clone and has its root in JOS Wiki. TWiki's home is at http://TWiki.org/ TWiki takes a lot of ideas from Ward Cunningham's remarkable Wiki Wiki ...
A WikiWord consists of two or more words with initial capitals, run together. When you type a WikiWord, you establish a hyperlink. It's as easy as that. WikiWords ...
Number of topics: 118
See also the faster WebTopicList
WebNotify is a subscription service to be automatically notified by email when topics change in the netfrag.org.TWiki web. This is a convenient service, so you do not have to come back and check all the time if something has changed. To subscribe to the service, please put yourself on the list below. The format is: 3 spaces * Main.yourWikiName - yourEmailAddress
Note: It is helpful to insert your name in alphabetical order (by first name -- ignore the "Main.") -- then you can find your name (or not) more easily if you wish to remove it or confirm that you are on the list.
Related topics: TWikiUsers, TWikiRegistration
The following settings are web preferences of the netfrag.org.TWiki web. These preferences overwrite the site-level preferences in TWikiPreferences, and can be overwritten by user preferences (your personal topic, i.e. TWikiGuest? in the netfrag.org.Main web)
Preferences:
Users or groups who are not / are allowed to view / change / rename topics in the TWiki web: (See TWikiAccessControl)
Set DENYWEBVIEW =
Set ALLOWWEBVIEW =
Set DENYWEBCHANGE =
Set ALLOWWEBCHANGE =
Set DENYWEBRENAME =
Set ALLOWWEBRENAME =
Users or groups allowed to change or rename this WebPreferences topic: (I.e. TWikiAdminGroup)
Set ALLOWTOPICCHANGE =
Set ALLOWTOPICRENAME =
Web preferences that are not allowed to be overridden by user preferences:
Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
Notes:
A preference is defined as: 6 spaces * Set NAME = value Example:
Set WEBBGCOLOR = #FFFFC0
Preferences are used as TWikiVariables by enclosing the name in percent signs. Example:
When you write variable %WEBBGCOLOR% , it gets expanded to #000000 .
The sequential order of the preference settings is significant. Define preferences that use other preferences first, i.e. set WEBCOPYRIGHT before WIKIWEBMASTER since %WEBCOPYRIGHT% uses the %WIKIWEBMASTER% variable.
You can introduce new preferences variables and use them in your topics and templates. There is no need to change the netfrag.org engine (Perl scripts).
Welcome TWikiGuest?,
You have reached a TWikiSite (pronounced twee-kee site). TWiki is a meeting place where people collaborate on common interests. Anyone can contribute using a regular Web browser. TWiki looks like a normal Web site, but it allows (and ecourages) everyone to edit the web pages and contribute their questions and input. It really is very simple to learn and use, and provides possibly the most powerful way to exchange and develop ideas online, in an open, uncomplicated environment.
How TWiki Works
Read: You can treat this site like any other. Browse, and follow interesting links. A couple of hints:
web: A TWikiSite is divided into webs; each one represents one subject, one area of collaboration. You can reach any web from the links in the upper right corner of every page.
topic: Each web is made up of hyperlinked topics - TWikiPages that appear in your browser.
What's new: Visit WebChanges in any TWiki web to see what other people are discussing and what's been added most recently.
Create an Account: To be able to write new content on this site, you'll need to create an account for yourself. It's simple, and only takes a minute: just visit TWikiRegistration and fill out the form. This will also create your personal home page.
Write: If you have something to say, speak your mind! Anyone can change or add to anything they see written in a TWiki topic. You can edit a topic from within your browser, using TWikiShorthand, a very simple markup language (you can also use HTML if you like, but you'll usually find you can get the same results more easily with TWikiShorthand). To contribute,
click the Edit link at the bottom of the page, edit the text, and then
click the [ Preview Changes ] button at the bottom of the page to see what your topic will look like (use the BACK button on your browser to go back and fix something.), and finally
click the [ Save Changes ] to save what you did.
But this is scary! Anybody can do anything! The concept at first may seem...strange. Uncontrollable. And yet, collaborating the Wiki way works! See WikiCulture. (You can define fine-grained TWikiAccessControl based on users groups if really necessary, and there's full revision control that retains all changes!)
Experiment: To get your virtual hands dirty, visit Test.Home in the netfrag.org.Test web.
Create a link: To link to another topic, start by editing an existing topic.
To create a link to a topic that already exists, type its JoinCapitalizedWords name (topics are automatically linked if they are WikiWords, names composed of two or more words with initial capitals, run together).
To create a link to a page that does not yet exist, make up and enter a NeverBeforeUsedPhrase. You are encouraged to include WikiWords in your content, for others to fill out later.
When you've saved the topic, and redisplayed it, the references to existing topics will be linked and the references to topics that don't exist will be followed by a linked "?" (question mark).
Create a topic:
To write something up for a new topic, click on the "?" (question mark) that follows a WikiWord.
To create a free-floating topic - a topic that is not linked from anywhere - type its WikiWord in the entry field at the top of any page. If the topic already exists you'll then be taken to it. If it doesn't exist, you'll then have the option to create it.
See the history of a topic: Click the Diffs link on the control strip at the bottom of every page to see a complete history of edits for that topic.
Attach files: Use your browser to upload and attach any type of file to a topic using the Attach link at the bottom of the page.
Organize: Use TWikiForms to include specific information wiht individual topics - for example, classify pages by subject, status, or date.
Learn more: TWikiTutorial takes you on a 20-minute tour of the TWiki essentials. WikiReferences has links to articles and books about online collaboration and Wiki technology in particular.
Main Features of TWiki
Edit existing pages or create new pages by using any Web browser.
Web pages are automatically linked. You do not need to learn HTML commands to link pages.
Very simple text formatting. Basically, you write a page the same way you would write an email.
Fast, full-text search with or without regular expressions.
All changes to pages and attachments are under revision control. Find out who changed what and when.
Fine-grained access control based on users and groups.
Automatic email notification when pages change.
File attachments: Upload and download any file as an attachment to a page, using your browser. This is similar to email file attachments, but it happens on web pages.
Topic locking: Users are warned if a page is being edited by another person, to avoid simultaneous page editing.
Templates and skins: Customize every possible aspect of the look and feel of each TWiki installation, down to the individual page level.
Plugins: A growing collection of plugins allows you to easily add optional extended functions, or to create your own.
Support: An active, helpful development community keeps TWiki support and development constantly moving forward.
Sandbox test area with all features enabled.
[ Changes?
| Search?
]
Experiment in an unrestricted hands-on web.
You can use color coding by web for identification and reference. Contact webmaster@netfrag.org if you need a separate collaboration web for your team. New TWiki webs can be added easily. To modify this table: { View | Edit }
A set of pages of information that are open and free for anyone to edit as they wish. They are stored on a server and managed using some Perl CGI scripts. The system creates cross-reference hyperlinks between pages automatically. See WelcomeGuest and TWikiSite for more information.
Back to:TWikiFAQ
-- PeterThoeny? - 27 Nov 2000
Everybody can edit any page, this is scary. Doesn't that lead to chaos?
Answer:
netfrag.org is one of many WikiWikiClones, the first one was built by Ward Cummingham. Collaborating the Wiki way is different from other collaboration tools like Usenet. A distinct Wiki culture forms around these tools:
Any and all information can be deleted by anyone. Wiki pages represent nothing but discussion and consensus because it's much easier to delete flames, spam and trivia than to indulge them. What remains is naturally meaningful.
Anyone can play. This sounds like a recipe for low signal - surely wiki gets hit by the unwashed masses as often as any other site. But to make any sort of impact on wiki you need to be able to generate content. So anyone can play, but only good players have any desire to keep playing.
Wiki is not WYSIWYG. Contra the dumbing down of programming, it's an intelligence test of sorts to be able to edit a wiki page. It's not rocket science, but it doesn't appeal to the TV-watchers. If it doesn't appeal, they don't participate, which leaves those of us who read and write to get on with rational discourse.
Wiki is far from real time. Folk have time to think, often days or weeks, before they follow up some wiki page. So what people write is well-considered.
Your name in WikiNotation. Usually your first and last name connected togther.
For example, Bill Clinton's WikiName is BillClinton.
Note: All users are in the netfrag.org.Main web. Prepend the "Main" name if you write a username in a topic, i.e. write Main.TWikiGuest to link to TWikiGuest?.
Presentation: TWiki Collaboration Tool - A Mature and Full Featured Platform for building Web Based Groupware Applications; by Peter Thoeny; TWiki:Main/TWikiPlatformPresentation
Book: The Knowledge Management Toolkit: Practical Techniques for Building a Knowledge Management System; by Amrit Tiwana; Prentice Hall PTR; ISBN:0130128538
Book: The Knowing-Doing Gap: How Smart Companies Turn Knowledge into Action; by Jeffrey Pfeffer and Robert I. Sutton; Harvard Business School Pr; ISBN:1578511240
Extreme Programming
Book: Extreme Programming Examined; by Giancarlo Succi and Michele Marchesi; Addison-Wesley Pub Co; ISBN:0201710404
Book: Extreme Programming in Practice; by James W. Newkirk and Robert C. Martin; Addison-Wesley Pub Co; ISBN:0201709376
Book: Extreme Programming Explored; by William C. Wake and Bill Wake; Addison-Wesley Pub Co; ISBN:0201733978
If you can enter text, you're ready for TWiki. With a few simple, intuitive TWikiShorthand rules, you'll be able to use plain text to create well-styled postings, instantly. Here's a fast-track guide to shorthand basics...
Separate each paragraph with a blank line.
To display a word or phrase in bold type, put it in asterisks: *bold type*.
To display a word or phrase in italic, put it in underscores: _italic_.
To display a word or phrase in bold italic, put it in double underscores: __bold italic__.
To link to another Wiki topic, type the WikiWord for that topic. To link to a Wiki topic in another web, type the name of the web, and a dot, first: Test.Home.
If you enter a WikiWord for a topic that doesn't exist, it'll appear highlighted, with question mark at the end, prompting you (or someone else) to start off the new topic by clicking the ? - NewTopic? (click the ?, but don't save, to preserve the example!).
When entering WikiName signatures - like, guest - include the Main as a prefix, since all TWiki member pages are in the Main web: Main.YourName.
For an external link, type the full URL: http://twiki.org.
To prevent a WikiWord from becoming a link, type <nop> first, <nop>NoLinkPlease.
To indent with a bullet, enter [space][space][space][asterisk][space].
Use multiples of 3 spaces to start nested bullets.
That's 3-6-9-...
Start items in a numbered list with [space][space][space][1][space].
The "1" (or any number) will be replaced by the correct number, in order.
Start counting spaces for bullets from the beginning of a new line.
To include an image, type its URL. You also can Attach an image to the page and display it with text =%ATTACHURL%/yourimagefilename.jpg=.
To display a word or phrase in MONOSPACED TYPE, put it in equal signs: =like this=. Use ==two== for bold: bold mono.
Use <pre> to enclose code excerpts, filenames, and other unformatted text, with the opening and closing tags on their own separate lines:
<pre>
unformatted text!
</pre>
Three (or more) consecutive hyphens expand into a horizontal rule: ---
See TWikiShorthand for the complete set of formatting rules.
A WikiWord consists of two or more words with initial capitals, run together.
When you type a WikiWord, you establish a hyperlink. It's as easy as that.
WikiWords are styled like this because:
It makes Wiki hyperlinks instantly recognizable
It leads to interesting Wiki topics
It avoids the need to fiddle with HTML tags
It avoids over-general topics because at least two words are required
Syntax of a WikiWord
Uppercase letter(s)
Lowercase letter(s)
Uppercase letter(s)
Optional lowercase or uppercase letter(s) or number(s)
T5Wiki: Name with number before the first lowercase letter
Know-How: Name with dashes in between
Hints
Insert WikiWords wherever you can. Rich linking helps to make a Wiki successful.
To stop a WikiWord from being turned into a hyperlink, insert the text <nop> immediately before the WikiWord.
A topic is usually presented in the singular. Plural WikiWords are automatically linked to the singular topic, i.e. the link WikiWords links to the topic WikiWord.
Sometimes you have to be creative to find a good WikiName. Examples:
To create a topic about the the Bread Slicer 1.2 product, use BreadSlicer1dot2 or BreadSlicer1pt2, but not BreadSlicer1.2.
To create a topic about year 2000, you could go for YearTwoK or YearTwoThousand, but not Year2K or Y2K or Y2000.
Turn acronyms into WikiWords, i.e. take FaqIndex for a "FAQ index" topic.
You can create nicer looking links by using double square brackets, i.e. write [[TWiki access control]] to get a link to TWikiAccessControl that looks like TWiki access control.
, an image.
Sample.txt
Smile.gif
To hide access control settings from normal browser viewing, place them in comment markers.
– Temporary: standard 88x31px logo ID button:
NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
Net::SMTP can be easily disabled (ex: if there is an installation error) by setting logo.
Since wabi-sabi represents a comprehensive Japanese world view or aesthetic system, it is difficult to explain precisely in western terms. According to Leonard Koren, wabi-sabi is the most conspicuous and characteristic feature of what we think of as traditional Japanese beauty and it "occupies roughly the same position in the Japanese pantheon of aesthetic values as do the Greek ideals of beauty and perfection in the West."
Wabi-sabi is a beauty of things imperfect, impermanent, and incomplete. It is the beauty of things modest and humble. It is the beauty of things unconventional.
The concepts of wabi-sabi correlate with the concepts of Zen Buddhism, as the first Japanese involved with wabi-sabi were tea masters, priests, and monks who practiced Zen. Zen Buddhism originated in India, traveled to China in the 6th century, and was first introduced in Japan around the 12th century. Zen emphasizes "direct, intuitive insight into transcendental truth beyond all intellectual conception." At the core of wabi- sabi is the importance of transcending ways of looking and thinking about things/existence.
